Install FTL: Hyperspace on Linux manually

There is an easier way

The easy install does all of this for you. Only continue if you would rather set everything up by hand, or you want to understand what it does.

1. Steam settings

   Skip this if you did not buy FTL on Steam.

   Right-click FTL: Faster Than Light in your library and open Properties.

   Show me how to open Properties

   

   Under General, untick Keep game saves in the Steam Cloud. Turn off Steam Cloud first. It restores outdated saves with broken state, which can keep Hyperspace from launching and will undo any save fix you try later.

   Show me the checkbox

   

   Then under Updates, set automatic updates to Only update this game when I launch it.

   Steam will undo your install

   If Steam updates FTL it replaces the patched game files, and Hyperspace stops loading.

   Your saves live in ~/.local/share/FasterThanLight.

   Hidden folders are not shown by default

   Open your home folder in your file manager and press Ctrl-H to show hidden files, or paste the path into its location bar.

   Rename FasterThanLight to FasterThanLight-backup, then launch FTL. The game makes a fresh folder, and your original saves stay in the backup if you ever want them back.

   Do this once, right after turning Steam Cloud off. Cloud sync leaves behind a save that Hyperspace cannot read, which freezes the game at the end of the loading bar.

2. Install the Hyperspace library

   Download FTL.Hyperspace.x.xx.x-Linux.zip from the latest release and extract it. Inside you will find:

   • Hyperspace.ftl keep this for the mod manager step
   • README.txt
   • OrdnerLinux/

     • Hyperspace.1.6.12.amd64.so
     • Hyperspace.1.6.13.amd64.so

   Which library you need depends on your FTL version. Launch FTL and read the version from the lower right of the main menu rather than guessing, then close the game.

   Your FTL version	Vendor	Library to copy
   1.6.13	Steam	Hyperspace.1.6.13.amd64.so
   1.6.12	GOG, Humble, DRM-free	Hyperspace.1.6.12.amd64.so

   1. Copy one Hyperspace library, the one matching your version, into the folder containing FTL.amd64.
   2. Open the FTL launch script in a text editor and add a line before exec:

   LD_PRELOAD=./Hyperspace.1.6.13.amd64.so exec "$here/$command.$arch" "$@"

   If the game starts without Hyperspace

   Some machines need LD_LIBRARY_PATH set as well. Use this form instead:

   export LD_LIBRARY_PATH="$here":"${LD_LIBRARY_PATH}"
   export LD_PRELOAD=Hyperspace.1.6.13.amd64.so
   exec "$here/$command.$arch" "$@"

   Requirements

   Multiverse wants 3 GB or more of RAM. Other Hyperspace mods vary.

3. Set up a mod manager

   You need a mod manager to patch .ftl files into the game. ftlman is the one to use unless a mod misbehaves under it. The rest of this guide follows whichever tab you pick.

   ftlman

   Ftlman is the recommended mod manager for FTL: Hyperspace modding. Actively maintained and supports Hyperspace updates

   If FTL is currently modded (ftl.dat is bigger than ~270 MB), revert it to vanilla first, either with your mod manager or by reinstalling the game.

   1. Download the build for your machine from the ftlman releases page.
   2. Extract the ftlman folder anywhere you like. It does not have to live in your FTL directory.
   3. Run ftlman. A Steam install is detected automatically. If yours sits somewhere non-standard, or you have more than one copy and want a specific one, open Settings and set FTL data directory yourself: the folder holding ftl.dat inside the game installation.

   Moving over from Slipstream

   Copy everything out of your Slipstream mods folder into ftlman/mods before the first run and your mod order carries across automatically.

   Slipstream

   The original manager, now deprecated.

   Use ftlman instead

   We recommend ftlman for any new installation. Only use Slipstream if you have a specific reason to.

   If FTL is currently modded (ftl.dat is bigger than ~270 MB), revert it to vanilla first, either with your mod manager or by reinstalling the game.

   1. Install Java. Slipstream will not run without it.
   2. Download Slipstream 1.9.1.
   3. Extract it to a folder you will keep.

   Achtung

   Slipstream 1.9.1 does not check whether ftl.dat is actually vanilla. It treats whatever it finds on first run as the baseline. Starting from a modded file causes problems

4. Patch Hyperspace in

   ftlman

   1. Turn off ftlman’s own Hyperspace installer, which would otherwise overwrite the files you installed by hand: in Settings, open Advanced settings and tick Disable Hyperspace installer.

      Show me the setting

      

   2. Put Hyperspace.ftl from the ZIP into the ftlman’s mods folder.

   3. Put your mods in the ftlman’s mods folder.
   4. Press Scan in the top right so ftlman can find them.
   5. Drag `Hyperspace.ftl` to the top of the list. Check the order, top to bottom:
      1. `Hyperspace.ftl`
      2. Your other mods

   6. Tick mods you want to use. Order matters, some mods specify that they must be loaded before (e.g. Multiverse Assets). To change order simply drag the mod up or down in the list.

      Keep Hyperspace.ftl on top

      Hyperspace.ftl must sit above every other mod in the list. Mods that ship their own hyperspace.xml, Multiverse among them, are patched after it and override it. Patching hyperspace.ftl below other mods may lead to a broken install.

   7. Press Apply.
   Slipstream

   1. Enable ZIP support: Preferences → allow_zip.

   2. Put Hyperspace.ftl from the ZIP into Slipstream’s mods folder, along with your mods.

   3. File → Re-Scan mods/ so Slipstream can find them.

   4. Tick mods you want to use. Order matters, some mods specify that they must be loaded before (e.g. Multiverse Assets). To change order simply drag the mod up or down in the list.

      Keep Hyperspace.ftl on top

      Hyperspace.ftl must sit above every other mod in the list. Mods that ship their own hyperspace.xml, Multiverse among them, are patched after it and override it. Patching hyperspace.ftl below other mods may lead to a broken install.

   5. Press Patch.

5. Check it worked

   Launch FTL. About halfway through the loading screen, and again on the menu, a small version string appears in the top right. That is Hyperspace reporting itself, and it means the binary is loaded.

   No version string

   Hyperspace is not loading at all. Check if you have copied all files in the right folders again.

   Error: hyperspace.xml not found

   The Hyperspace.ftl mod was not patched in. Run mod manager again and verify either Multiverse mod files or hyperspace.ftl is selected and patched

   Getting a Failed to install hook error instead? SELinux is blocking the library, which is common on Fedora. See the fix.

Hyperspace is now installed and ready to play. Everything below is optional.

Adding Multiverse

Multiverse is the largest mod built on Hyperspace, and it installs differently from everything else.

1. Open the Multiverse Official Downloads board and pick the newest [FTL MULTIVERSE BASE MOD] thread.

2. In the first post, scroll to Manual install and download both the DATA and ASSETS files. Ignore the installer above them, that one is Windows-only and does its own thing.

   Alternative way to download is to use Multiverse release thread under DOWNLOAD RAW FILES.

3. Put both .zip files in your mod manager’s mods folder.

ftlman

1. Press Scan in the top right so the new files show up
2. If ftlman installed Hyperspace for you (you have not disabled the installer in Settings → Advanced settings), skip this step. If you installed Hyperspace manually, drag Hyperspace.ftl to the top of the list. It must be above all other mods.
3. Drag Multiverse Assets.zip above Multiverse Data.zip
4. Check the order, top to bottom:
   1. Hyperspace.ftl (optional)
   2. Multiverse Assets.zip
   3. Multiverse Data.zip
5. Select the mods: click each entry until it is highlighted blue
6. Press Apply

Show me what it should look like

Slipstream

1. Enable ZIP support: Preferences → allow_zip, then File → Re-Scan mods/
2. Drag Multiverse Assets.zip above Multiverse Data.zip
3. Tick the checkboxes of both, plus any Multiverse-compatible add-ons
4. Leave Hyperspace.ftl unticked
5. Press Patch

Only add Multiverse-compatible mods

Anything not built for Multiverse can conflict with it. Add them one at a time so you know which one broke things, and ask on Discord if you are unsure about a particular favourite.

When Hyperspace updates

Updating Hyperspace does not disturb your saves, but you do need to re-patch Multiverse afterwards.

Uninstalling

1. Put ftl.dat back to vanilla

   Deleting the mod files is not enough on its own. ftl.dat still holds the patched content and has to be put back to vanilla.

   ftlman

   Delete ftl.dat and rename ftl.dat.vanilla back to ftl.dat.

   Slipstream

   Slipstream keeps no vanilla copy. Untick every mod and press Patch again: patching with nothing selected is what writes the original ftl.dat back.

2. Remove the Hyperspace files

   Delete the Hyperspace.*.so file from your FTL folder.

3. Undo the launch script edit

   Remove the LD_PRELOAD line you added to the FTL script.