Skip to content

Idiot's guide to macOS installation

Jump to bottom
Tobey Blaber edited this page Nov 12, 2023 · 43 revisions

This guide was written for macOS Sonoma. The instructions below should still work for other versions of macOS, but there may be some slight differences.

If you run into any unexpected issues while following this guide, join the Subnautica Modding discord server and send a message in one of the #help-and-support channels describing your problem. Make sure to mention you were following this guide, and what step you got stuck on, and I or someone else will help you out.

⚠️ IMPORTANT NOTE ⚠️

If you wish to also use QModManager, it is highly recommended to follow this guide first to get BepInEx working, and then follow the guide to installing QModManager on macOS.

Please note that QModManager can only be used on the legacy branch of Subnautica, which is only available if you own the game on Steam.

Prerequisites

If you don't own the game on Steam, you'll need to add it to Steam as a non-Steam game to run BepInEx on macOS. Follow the guide to add a non-Steam game to Steam if you're unsure how.

ℹ️ If for whatever reason adding the game to Steam as a non-Steam doesn't work out for you, there is an alternative method to install BepInEx, but it is not well-supported. Please only use it as a last resort. Click here for a guide and more information.

Automated Installation with gib

By far the easiest, most foolproof way to get BepInEx working for Subnautica is to to use gib (tobey's Guided Installer for BepInEx).

Simply download Tobey's BepInEx Pack for Subnautica, then follow the instructions in the gib README to get BepInEx up and running.

Manual Installation

If you're a glutton for punishment, follow these instructions to install manually:

  1. Step one is to download BepInEx and put the files in your Subnautica installation folder:

    1. Download Tobey's BepInEx Pack for Subnautica. You can get this either from the Files tab on Nexus Mods, or here on GitHub, whichever you prefer.

    2. Find Subnautica in your Steam library, then right-click it and choose Manage -> Browse local files.

      ⚠️ If you added Subnautica to Steam as a non-Steam game, simply open the Finder window where the Subnautica app (Subnautica.app) is located instead.

      image

    3. Move the contents of the BepInEx archive you downloaded into the folder with your Subnautica app (Subnautica.app).

      ⚠️ The contents of the archive are the files and folders inside the outer folder generated when you/Safari unzipped the downloaded archive. You want those inner files and folders (run_bepinex.sh etc.) in the same folder as the Subnautica app like the below screenshot! Getting this wrong may result in some mods failing to work properly!

      image

      ℹ️ The contents of the archive may have changed since this screenshot was taken - make sure to move all files and folders from inside the downloaded archive into the folder, whether they appear in this screenshot or not. However, the run_bepinex.sh file should always be here - in the same folder as the Subnautica app - as it is integral to this guide.

  2. For step two, we need to make the run_bepinex.sh file executable, as this shell script is how we will launch the game with mods:

    1. Open Terminal from Launchpad by pressing Command + Space, typing terminal and pressing enter.

      image

      ℹ️ This guide hasn't been tested with iTerm2 or other terminal apps. Use the standard terminal if you have problems.

    2. In the Terminal window, type the following command followed by a Space. Don't press enter yet!

      chmod u+x

      ⚠️ The Space after the u+x is important! Better to have too many spaces than not enough 😄

    3. Now, drag the run_bepinex.sh file from your Subnautica folder into the Terminal window:

      image

    4. Press enter to run the command:

      image

      ℹ️ It's normal for there to be no output after running the command. If you get output, it probably means you did something wrong. Check that you have a Space after the u+x and before the path to run_bepinex.sh, like in the screenshot above.

    5. You can now close the Terminal window.

  3. Step three is telling Steam to launch the game via the run_bepinex.sh script:

    1. Back in the Finder window of your Subnautica folder, right-click the run_bepinex.sh file, and holding the Option key, click Copy "run_bepinex.sh" as Pathname.

      Your clipboard should now contain the full path to the run_bepinex.sh script in your Subnautica folder when you paste it with Command + V. For example, on my machine it looks like this:

      /Users/toebean/Library/Application Support/Steam/steamapps/common/Subnautica/run_bepinex.sh

    2. In your Steam library, right-click Subnautica and this time choose Properties... from the menu.

    3. In the General tab (or the Shortcut tab if you have added Subnautica as a non-Steam game), set your launch options like this, replacing <PASTE THE PATHNAME HERE> with the pathname you just copied:

      "<PASTE THE PATHNAME HERE>" %command%

      ⚠️ Make sure to remove the <>, but leave in the ""! It should look like this once pasted properly:

      image

      ⚠️ The quotes surrounding the path to run_bepinex.sh are important! Don't forget them!

  4. Run the game via Steam.

    If you see a prompt warning you that "libdoorstop_x64.dylib" cannot be opened, follow these steps:

    1. Open System Preferences.
    2. Go to Security & Privacy and select the General tab.
    3. Towards the bottom you should see a message saying that the program was blocked from opening. Click Open Anyway and confirm any prompts that pop up.
    4. Run the game via Steam, confirming any prompts that pop up.

At this point, assuming the game opens as normal, you're done! BepInEx is installed! You won't see any indication in-game that BepInEx is running, so it is suggested to install a simple plugin such as Configuration Manager to check it's all working:

  1. Download the latest version of Configuration Manager.

  2. Drag the contents of the archive into the BepInEx folder so that the .dll and .xml files are in the BepInEx\plugins folder. It should look like this when done correctly:

    image

  3. Run the game via Steam. Once you reach the main menu, press F5, and if everything is working you should see the Configuration Manager window pop up:

    image

And now you're ready to go wild installing mods. Have fun!

If you wish to also use QModManager, you will need to next follow the guide to installing QModManager on macOS.

Please note that QModManager can only be used on the legacy branch of Subnautica, which is only available if you own the game on Steam.

If you ran into any unexpected issues while following this guide, join the Subnautica Modding discord server and send a message in one of the #help-and-support channels describing your problem. Make sure to mention you were following this guide, and what step you got stuck on, and I or someone else will help you out.

Clone this wiki locally