Installation

Substance supports all three main desktop operating systems: macOS, Windows, and Linux. Its main prerequisite is Oracle VirtualBox, which also supports these platforms.

If an existing substance project is going to be used, make sure to check how much RAM and disk space will be required before procceding with the installation.

On macOS

Substance is not compatible with the Python distribution that ships with macOS. You must use Homebrew to install the latest Python 2.x release.

  1. Download and install Oracle VirtualBox. Make sure VBoxManage is in your PATH environment variable.

  2. Make sure Xcode CLI is installed:

    $ xcode-select --install

  3. Ensure Homebrew is installed:

    $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  4. Install Homebrew’s Python (Version 3 and up) distribution:

    $ brew install python

  5. Make sure that you are running python 3.x when installing substance. If there is 2 versions of python installed python/pip will probably be 2.7, and python3/pip3 3.x

  6. The python3 installed by homebrew should be located under /usr/local/bin. The python version under /usr/bin is the one installed by default in MacOS. You can verify python version with --version argument and locate executable with which command.

    If homebrew’s version is not found that’s probably because it is not in your PATH. Use the command brew doctor, copy the command to add it to your PATH and restart your terminal.

  7. Ensure pip3 is up to date:

    $ sudo pip3 install -U pip

  8. Install substance:

    $ sudo pip3 install substance

On Windows (WSL)

Disclaimer: Substance has only been tested on Windows 10 Pro 64-bit edition.

  1. Install Oracle VirtualBox. Make sure VBoxManage is in your PATH environment variable (System -> Advanced System Settings -> Environment Variables -> Path -> add path to your VirtualBox installation directory).

  2. Open PowerShell (or cmd) as Administrator and run:

    Copy
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

  3. Restart the computer

  4. Download and install your distribution of choice. We recommend Debian/stretch from the Microsoft Store.

    1. Open the Microsoft Store and choose your favorite Linux distribution.
    2. Debian GNU/Linux (Stretch)

  5. Install python3 on your linux distribution:

    $ apt-get update
$ apt-get install -y python3 python3-dev python3-pip

  6. Install substance with pip:

    $ pip3 install substance

The home directory used by substance in WSL will be your Windows user’s home directory (for example: C:\Users\USERNAME) This is to allow your projects and code can be edited and modified from both programs inside WSL and outside.

For simplicity, the sync process (unison) within WSL will run the linux version.

On Windows (Cygwin)

Due to poor support for command-line utilities on Windows, Cygwin is required to run Substance on Windows.

Disclaimer: Substance has only been tested on Windows 10 Pro 64-bit edition. Installation on 32-bit Windows is NOT supported.

  1. Install Oracle VirtualBox. Make sure VBoxManage is in your PATH environment variable (System -> Advanced System Settings -> Environment Variables -> Path -> add path to your VirtualBox installation directory).

  2. Install Cygwin 64-bit. Here are the steps:

    1. Create a directory C:\cygwin64 on your main drive. Create a subdirectory named “setup” inside that directory.
    2. Download setup-x86-64.exe from https://www.cygwin.com/ and place it in C:\cygwin64\setup
    3. Double-click on setup-x86-64.exe, and perform the install. Keep the default location and make sure the following packages are selected:
      • mintty (under “Shells”)
      • make (under “Devel”)
      • git (under “Devel”)
      • gcc-core (under “Devel”)
      • python2 (under “Python”)
      • python2-devel (under “Python”)
      • libffi-devel (under “Libs”)
      • openssl-devel (under “Net”)
    4. Optionally, you can create a shortcut to setup-x86-64.exe and add it to your Start menu; you can re-run the setup whenever you want to add or remove packages to your Cygwin install.

  3. Launch Cygwin Terminal (mintty). All the magic happens from there!

  4. Run which python && which pip to make SURE that you are running both executables from /usr/bin, NOT something like C:\Python!

  5. Execute the command python --version. You should see an output like Python 2.7.12.

  6. Make sure pip is installed and is upgraded to the latest version by running the commands:

    $ python -m ensurepip
$ pip install -U pip

  7. Install substance:

    $ pip install substance

On Linux

Make sure you are running a 64-bit Linux distribution. 32-bit is NOT supported. Substance has been tested on Mint, Ubuntu, and Arch Linux.

  1. Install Oracle VirtualBox. Make sure VBoxManage is in your PATH environment variable.

  2. Install the following software using your package manager. Of course, depending on the distribution, the package names may slightly vary (but you will usually find a proper equivalent):

    • git
    • build-essential
    • libffi-devel
    • openssl-devel

  3. Make sure to have Python 2 available. On some distributions (like Ubuntu 14.04), this is the default Python interpreter, which means you can use python and pip. On other, more state-of-the-art distributions (like Arch), you need to install a separate python2 package and use the commands python2 and pip2 for the rest of this guide. Also install python-devel or python2-devel, depending on your distribution.

  4. Install substance:

    $ sudo pip install substance

Ubuntu 20.04 LTS

This version of Ubuntu already comes with the development libraries required for substance.

  1. Install Oracle VirtualBox.

  2. Substance requires Python 3 and pip 3. Python 3 will be already installed and it is accessible with python3. Install pip 3 with:

    $ sudo apt install pip3

  3. Install substance:

    $ sudo pip3 install substance

Make sure you use Python 3 and pip 3, and not the Python 2 counterpart.

Upgrading Substance to a new version

On all supported platforms, these commands will allow you to update the Substance on your machine without losing data or engines:

$ sudo pip uninstall substance
$ sudo pip install substance