(Last updated: January 20, 2018)
Borderlands 2 + TPS UCP Logos

I recently became aware of the Borderlands 2 Unofficial Community Patch (UCP) and the Borderlands The Pre-Sequel Unofficial Community Patch (UCP), some fan-produced mods/patches to Borderlands 2 and TPS which attempt to balance and change aspects of the games that some folks had felt were lacking. Many of the changes relate to providing buffs to weapons seen as underperforming, for instance.

(Additionally, it turns out that there's a very lively modding scene for BL2 and TPS in general, which was news to me, though clearly I'm late to the game here. Check out the BLCM Project on github, or its more easily-browsable wiki.)

Folks running Windows have it easy: there are a few apps linked on the UCP pages which basically just take care of everything for you and let you get right to the action, but on Linux there's more fiddling to do. In particular, finding out how to enable these for The Pre-Sequel required quite a bit of Googling around to figure out. So, I figured I'd collect all the necessary information on one page. This may help out Mac users as well, though this page is only written with Linux in mind.


I feel I should point out that I didn't discover any of these techniques myself. This page is just an aggregation of a variety of sources online, to hopefully save future Linux BL2/TPS patchers a bit of trouble.

If there's anything in here which is wrong, incomplete, needs streamlining, or just if there's something else which would be useful to have on this page, feel free to contact me!

The Short Version

This page is pretty wordy and probably doesn't need to be. Here's a barebones version of what you'll want to do. The overly-verbose stuff will follow, if you want more details!

  1. Edit your ~/.local/share/aspyr-media/<game>/willowgame/config/willowinput.ini to include a keybinding like ConsoleKey=Tilde
  2. Decompress the game's steamassets/willowgame/cookedpcconsole/engine.upk using Unreal Package Decompressor (using Wine)
  3. Hex-edit the decompressed file, replacing these hex strings (there will be two instances in the file which need replacing):
    • Borderlands 2: 1B E9 471B A5 14
    • Pre-Sequel: 1B 0A 491B A2 14
  4. Replace engine.upk with your patched version, rename/move engine.upk.uncompressed_size out of the way
  5. Place the UCP patch inside the game's steamassets/binaries directory, with an all-lowercase filename
  6. Load the patch every time you start the game, using the following technique:
    1. Start the game, click any key to get to the main menu
    2. At the main menu, hit escape and say Yes to get back to the loading screen.
    3. Bring down the console, run: exec patch.txt (Or whatever filename you used)
  7. To use FilterTool to manage the patch file, if you want (this is entirely optional), launch it with: java -XX:MaxHeapFreeRatio=50 -jar FilterTool.jar

As promised, the much wordier version follows:

Step 1: Configure a Console Hotkey

This is the easiest of the steps. Simply open up your willowinput.ini file, which will be found here:

~/.local/share/aspyr-media/borderlands 2/willowgame/config/willowinput.ini
~/.local/share/aspyr-media/borderlands the pre-sequel/willowgame/config/willowinput.ini

Then locate the [Engine.Console] section and set the following line:


You could also use F6 or some other key, though for console access in FPSes, using the tilde/backtick key is customary.

At this point, you'll be able to bring up the console, but the actually-useful console commands won't be active: the game will pretend you wanted to "say" that command in the ingame chat and just send it out there, rather than actually running anything. So the next step is to get rid of that behavior.

Step 2: Enable the Fully-Featured Console

In online directions for Windows users, you'll see instructions to use a hex editor on Borderlands2.exe or the like, but the hex strings they specify don't actually exist in the Linux binaries for the game (which isn't really surprising).

Instead, you've got to patch the file engine.upk, which will be found in this location:

SteamApps/common/Borderlands 2/steamassets/willowgame/cookedpcconsole/engine.upk

Note: If you're doing this on Borderlands 2, you can skip the hex-editing if you want, because one of the Windows utilities includes a pre-patched engine.upk in its repostitory: https://github.com/bugworm/BorderlandsPatcher - so feel free to get it from there if you like, if you trust it (as of January 2018, I can confirm that the file only contains the changes I'm about to describe).

The game's packaged engine.upk is compressed, and you have to hex-edit the uncompressed version of the file. At the moment, I only know of one way to do this: using the "Unreal Package Decompressor" found at http://www.gildor.org/downloads. That's a Windows program which must be run via Wine, but it works quite well.

So, download decompress.zip, unzip it to get decompress.exe, and then run it against engine.upk like so:

$ wine decompress.exe engine.upk

That will create a new directory named unpacked, and inside that directory will be the uncompressed engine.upk.

Now edit the uncompressed engine.upk inside a hex editor. I personally just use the bare-bones console hex editor named hexedit, which I assume is available on most distros. The value you want to change depends on whether you're editing the file for Borderlands 2 or The Pre-Sequel, though in either case there are two locations in the file where you need to change it:

  Change From   Change To
Borderlands 2: 1B E9 47 1B A5 14
The Pre-Sequel: 1B 0A 49 1B A2 14

Again, remember that there will be two locations in the file which require that change.

Now that you have a patched engine.upk, rename/move the original engine.upk out of the way, replace it with your edited engine.upk, and also rename/move the accompanying file, engine.upk.uncompressed_size. You won't replace engine.upk.uncompressed_size with anything, because the replacement engine.upk is already uncompressed.

Note: One of the Reddit posts I linked to also talks about hex-editing willowgame.upk. This is not actually necessary for the UCP, or for other mods found online. The edits to willowgame.upk just enable some special development commands like changing levels, setting player level/money, etc.

At this point, you should be able to launch BL2/TPS and find out if the patching worked. Pull down the console and type some nonsense like "foo". Without the patching, the game will just put "foo" into the ingame chat. If the patching was successful, you'll get a notice in the console saying "Command not recognized: foo".

Step 3: Install and run the patch!

Okay, we're through the tricky bits! All you've got to do at this point is put the patch file (using an all-lowercase filename) inside the game's binaries directory, which will be at:

SteamApps/common/Borderlands 2/steamassets/binaries

Then, from the game's console, on the main loading screen, you can send it the following command, substituting the filename for whatever you used:

exec patch.txt

If it worked, there should be a brief pause while the game executes all the commands saved in the patch file. As of January 2018, the current Borderlands 2 patch file generates four errors related to specific weapons, for me, so you'll probably see those as well. I assume that's something that happens on Windows as well, though it could be something specific to Linux, I suppose.

There are two gotchas which you'll want to keep in mind:

  1. The Linux version of B2/TPS requires that the filename be in all-lowercase. When you use the console to specify the filename, it'll silently convert what you typed into lowercase when trying to load, even if you type it in uppercase. (This will result in a confusing error message, since the error message will retain your uppercase characters.)
  2. The patches will only actually work if you load them from the main "loading" screen, which just has the big ol' Borderlands logo on it with "Press any Key" at the bottom, not from the main menu. You'll also want to only load the patch after the game has discovered all your DLC, so the whole loading procedure should be:

    1. Start the game, click any key to get to the main menu
    2. At the main menu, hit escape and say Yes to get back to the loading screen.
    3. Then load the patch.
    If you load the patch file from the main menu, there'll be no indication that anything failed, but the patch won't actually have taken effect. (The easiest way to verify is to observe that Eridium/Moonstone doesn't automatically get picked up like money.)

Note that you'll have to run the "exec patch.txt" command once every time you launch B2/TPS. I think I saw something about a technique to have it auto-execute, but I didn't look into it and don't currently care enough to dig around more.

Step 4: Using UCP's FilterTool (optional)

One of the neat utilities provided by the BLCM project is a utility called UCP Filter Tool. On Windows, this utility handles all the necessary patching and configuration shown above, which doesn't work on Linux, of course. But it also provides a great method for enabling/disabling parts of the UCP patch on a case-by-case basis (in case you want some functionality but not others), and also aggregating other mods into one big patch file, so you only have to "exec patch.txt" for a single filename. That stuff works fine on Linux, so it's worth setting up.

Running FilterTool is entirely optional, though. If you want to run UCP as-is without tweaking any of it, there's no need to run it. Even if you do want to tweak anything in there, the patch files are just text files and you can edit them in any text editor. Just use a hash sign (#) to comment out any commands you don't want to run.

Regardless, to run FilterTool, download the zipfile from the Dropbox link in FilterTool's documentation, unzip it, and, for convenience, copy FilterTool.jar into your game's binaries directory (the same place you put the patch file):

SteamApps/common/Borderlands 2/steamassets/binaries

FilterTool is a Java app, so you need a Java runtime installed. OpenJDK, the default for many distributions, should be fine. On Linux (and Mac, as it turns out), you do need to specify one strange commandline option when launching, or the utility will exit almost immediately with no error messages or warnings whatsoever. From the same directory as the patch file and FilterTool.jar, you'd run:

$ java -XX:MaxHeapFreeRatio=50 -jar FilterTool.jar

FilterTool expects that the filename you're working on will be "Patch.txt", with a captial "P", which is at odds with the case requirements of actually running the patch inside Borderlands itself. The utility does let you open/save arbitrary filenames, but personally I just bowed to convenience and set up a symlink like so:

lrwxrwxrwx 1 pez pez        9 Jan 20 23:01 patch.txt -> Patch.txt
-rw-r--r-- 1 pez pez  2209697 Jan 20 19:27 Patch.txt

So FilterTool is operating on the "real" file, while the symlink is there to provide Borderlands with a lowercase version of the file to load. It's a bit hokey, but it's convenient.


So, that's it! Not a trivial amount of work to get going, really, though in the end it's pretty straightforward. The main hurdle that I had was that all the information to get this going on Linux was spread out over a number of different places online, and it took awhile to aggregate all the info and figure out what needed doing. Hopefully this page ends up helping someone else get to those answers a little more quickly!

As I said above, if there's anything in here which is wrong, incomplete, needs streamlining, or just if there's something else which would be useful to have on this page, feel free to contact me!


January 20, 2018
  • Initial post