Install FTL: Hyperspace on macOS manually

There is an easier way

The macOS installer does all of this for you. Only continue if it will not run on your machine, 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 ~/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

5. Set up a mod manager

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

   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. If FTL is currently modded, revert it to vanilla first.
   4. 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.

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

7. 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 release thread and scroll to DOWNLOAD RAW FILES (OTHER PLATFORMS, UPDATES, MANUAL INSTALL). Ignore the installer above it, that one is Windows-only and does its own thing.
2. Download both files listed there, the Assets File and the Data File.
3. Put both .zip files in your mod manager’s mods folder.
4. Patch them in this order, and nothing else:

ftlman

• Press Scan in the top right so the new files show up
• Drag Multiverse Assets above Multiverse Data
• Tick both
• Leave Hyperspace unticked
• Press Apply

Show me what it should look like

Do not patch Hyperspace.ftl with Multiverse

Multiverse already contains everything Hyperspace.ftl provides. Patching both is the single most common cause of a broken install.

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.