These are the docs for 12.2, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

Manual setup guide for macOS

Note: For a simpler setup experience, try the SpatialOS setup guide that uses homebrew.

1. System requirements

We support up-to-date versions of macOS Sierra, El Capitan and High Sierra.

Before following the setup guide check that your machine meets the hardware requirements.

If you’re using a corporate network with a strict firewall, raise a support request or ask on our forums and we’ll take you through some custom setup steps.

2. Set up the SpatialOS CLI

To set up the SpatialOS CLI (spatial):

  1. Download spatial for macOS (64bit): Download.

    By downloading spatial, you agree to the SpatialOS EULA.

  2. Put spatial in a directory.

    For example, bin in your home directory: mkdir -p $HOME/bin && mv $HOME/Downloads/spatial $HOME/bin.

  3. Add the directory to your PATH. To do so:

    1. Open a terminal window.
    2. Move into home directory: run cd.
    3. Determine which configuration file to use (you will need to know your configuration file again in later steps): run ls -a ~

      • If you have a .bash_profile, that’s your configuration file.
      • Otherwise, if you have a .bash_login, that’s your configuration file.
      • Otherwise, if you have a .profile, that’s your configuration file.
      • If you don’t have any of these files, you can use .bash_profile (which you’ll create in the next step).
    4. Add the location of spatial to the PATH variable: run echo 'export PATH=$PATH:/path_to_spatial_here' >> ~/your_config_file_here

      For example: echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile

  4. Make sure spatial is executable: run chmod +x /path_to_spatial_here.

  5. Restart your terminal window to register the changes made to the path.

  6. Check this succeeded by running spatial update in your terminal. You should get the output:

    Current version of the 'spatial' command-line tool: <version number>

    Attempting to download the latest version...

3. Set up Unity (optional)

To use the Unity SDK, even if you’ve already got Unity installed, you must follow these steps, because SpatialOS only supports specific versions of Unity, and requires specific build support.

Unity versions 5.6.0 and 2017.3.0 have been tested with SpatialOS. Other versions may work fine, but have not been extensively tested.

Install Unity version 2017.3.0 and the optional extras that SpatialOS requires:

  1. Go to the Unity Download Archive.
  2. Next to version 2017.3.0, from the “Downloads (Mac)” dropdown, select “Unity Installer”.
  3. Run the installer. In addition to the defaults, select Linux Build Support and Windows Build Support:

    Unity screenshot

  4. Install Unity into the default installation directory.

    Alternatively, you can set the environment variable UNITY_HOME to your customized Unity installation folder. For example, if you installed Unity to /Applications/Unity2017.3.0, then set UNITY_HOME to /Applications/Unity2017.3.0. This path cannot have spaces in it.

  5. Launch Unity and complete the registration process.

Important: Once you’ve set up a project, you’ll need to set the path to spatial from the Unity SpatialOS editor window. See the Unity SpatialOS editor window page for instructions.

4. (optional) Install the Launcher

If you want to run a game client to connect to a SpatialOS game running in the cloud, you must install the Launcher.

  1. Download the Launcher.
  2. Follow the instructions in the installation wizard.

5. Next steps

You’ve now set up your machine for development with SpatialOS!

Recommended: To learn how to use SpatialOS and experiment with its main APIs, try the Pirates tutorial (Unity).

If you’d just like to find out about what SpatialOS is:

To get started building something of your own, go to and use one of the repositories there as a starting point.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums