Building NuPIC


Currently Supported Platforms:

  • 64-bit Linux
  • 64-bit Windows
  • Mac OS X
  • Docker

Normal Installation

Simply follow the installation instructions in the README.

Compiling from Source Code

Compilation Guides

Some of these guides have not been updated for different platforms. If you find discrepancies, please update.

Compile Dependencies

You will need to install the following dependencies in order to compile nupic.core and nupic:

Code Setup


If you’re only interested in using NuPIC, you don’t need a GitHub account to get a read-only checkout. You don’t even need git. If you simply want to download the latest zip file with the complete source code, you can do so by following these links and extracting the resulting files to your files system:

If you want to use git:

  • Follow the Github instructions to set up git.
  • Clone the nupic.core repository: git clone
  • Clone the nupic repository: git clone


NuPIC is a pure python project, and [NuPIC Core](NuPIC Core is a C++ project with SWiG Python bindings that generates the nupic.bindings python extension. NuPIC depends upon this module for faster algorithm performance. All HTM algorithms are implemented in both places (Python and C++).


Move into the NuPIC installation directory and run the following command to build and install NuPIC onto your system:

    cd $NUPIC
    python develop --user

If you get a gcc exit code 1, you may consider running this instead:

CC=clang CXX=clang++ python develop --user

If you are installing on Mac OS X, you should add the instruction ARCHFLAGS="-arch x86_64" before the python call:

ARCHFLAGS="-arch x86_64" python develop --user

Note: In the above instructions we are relying on the --user flag to install to a location in your home directory. Doing this, you may need to add this location to your $PATH and $PYTHONPATH environment variables.

Implicit in calling python develop, a release of nupic.bindings will be downloaded from that matches the version specified in requirements.txt. If, prior to installing nupic, you download, build, and install nupic.bindings from source, then you will have a pre-release version installed, as indicated by the .dev0 suffix in the version. The nupic installation process is cognizant of this and will not attempt to install nupic.bindings in the presence of a pre-release version and it is up to you, as the developer, to upgrade or downgrade nupic.bindings to match (or not, if you prefer).

If, after installing nupic without having already downloaded, built, and installed nupic.bindings from source and you decide to do so, you will need to explicitly remove the nupic.bindings release installed by nupic by uninstalling NuPIC. Subsequent attempts to install, or re-install nupic will bypass the nupic.bindings installation process, and it is up to you to upgrade nupic.bindings separately.

Once it is installed, you can import NuPIC library to your python script using:

import nupic

To ensure nupic.bindings was installed properly as well, try running:

import nupic.math

This package uses the math module from nupic.bindings, and will fail if not installed properly.

For examples, tutorials, and screencasts about using NuPIC, see the Using NuPIC wiki page.

NuPIC Core

The nupic repo is directly dependent on nupic.core.

View the nupic.core README for compilation instructions

And the Platform-Specific Build Instructions section below for further information.

Running Tests

If you are going to run tests, you might need to add py.test to your $PATH for tests to run. This will be in different locations depending on your python environment, so we’ll leave this up to you. Then you can run tests with the following command:

./scripts/ [-u] [-i] [-w] [-a]

The options are for -u unit tests, -i integration tests, -w swarming tests, and -a all tests. Swarming tests require MySQL.

Platform-Specific Build Instructions

Separate instructions are available for Running NuPIC on:

For advanced build options, see Development Tips.

Using an IDE

See our Development Tips wiki page for details.

To run the tests:

  • Run any test project from your IDE (check output panel to see the results).
1 Like