Install FTL: Hyperspace on macOS 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.

Keep a vanilla copy

Duplicate FTL.app somewhere outside the game folder before you patch anything. The copy will stay vanilla, so you can launch modded and vanilla versions whenever you like without unpatching, and it doubles as a clean source if an install goes wrong.

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 ~/Library/Application Support/FasterThanLight.

   Library is hidden by default

   Open your home folder in Finder and press Cmd + Shift + . to show hidden files, or press Cmd + Shift + G and paste the path.

   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. Find your FTL folder

   Vendor	Location
   Steam	~/Library/Application Support/Steam/steamapps/common/FTL Faster Than Light/
   GOG	/Applications/

   In Finder, press Cmd + Shift + G and paste the path. Steam users can also right-click FTL in their library and choose Manage → Browse Local Files.

3. Point the app at Hyperspace

   Right-click FTL.app, choose Show Package Contents, open Contents, and open Info.plist in a text editor.

   Change:

   <key>CFBundleExecutable</key>
   <string>FTL</string>

   to:

   <key>CFBundleExecutable</key>
   <string>Hyperspace.command</string>

   While you are in there, note CFBundleVersion. You need it next.

4. Copy the Hyperspace files

   Download FTL.Hyperspace.x.xx.x-MacOS.zip from the latest release. From the MacOS/ folder inside it, copy into Contents/MacOS:

   • Hyperspace.command
   • exactly one dylib matching the version you just noted: Hyperspace.1.6.13.amd64.dylib or Hyperspace.1.6.12.amd64.dylib

   Leave Hyperspace.ftl where it is for now. You need it in step 6.

5. Set up a mod manager

   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.

   Point ftlman at FTL.app/Contents/Resources, the folder holding ftl.dat. In Finder you can right-click ftl.dat, hold Option, and choose Copy as Pathname, then delete the trailing ftl.dat from the path. Click Scan.

   Note

   The error “FTL executable not found” is expected here and can be ignored.

6. 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.

7. Sign the app

   macOS refuses to run the patched app until it is signed.

   1. Open Terminal.

   2. Paste this in, then press the space bar:

      codesign -f -s - --timestamp=none --all-architectures --deep

   3. Drag FTL.app from Finder into the Terminal window. Its full path is filled in for you, so there is nothing to type.

   4. Press Return.

8. Launch

   Open FTL.app directly. Do not launch it through Steam.

Coming from the old wrapper?

The wrapper saved to ~/Documents/My Games/FTL Faster Than Light instead. If your progress looks missing afterwards, see migrating your saves before treating it as corruption.

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

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

Right-click FTL.app, choose Show Package Contents, then:

1. In Contents/Info.plist, change Hyperspace.command back to FTL.
2. Delete Hyperspace.command and Hyperspace.*.dylib from Contents/MacOS.
3. In Contents/Resources, delete ftl.dat and rename ftl.dat.vanilla to ftl.dat.