Build and Installation FAQ

General Advice

  • Make sure you’re using a recent version of pip.

If these FAQ do not address your build/installation problem, please post a new topic in the NuPIC Installation Help Forum for additional help.

I’m having trouble updating to a newer version of NuPIC

First, ensure you have uninstalled all old versions of NuPIC by running the following pip commands several times (until pip tells you there is nothing to uninstall):

pip uninstall nupic -y
pip uninstall nupic.bindings -y

Now, try reinstalling either from source or binary files using the README instructions.

permissions errors on installation

Try running the python installation command with the --user option. Alternatively, run with sudo (not recommended).

missing Python.h file

You must install Python 2.7 development headers. This will be different depending on your environment.

  • OS X
    • Install XCode
    • Install XCode Command Line Tools: xcode-select --install
  • Ubuntu: sudo apt-get python-dev
  • Debian: sudo yum install python-dev
  • Windows: Install a 2.7.9+ x86-64 msi version

OS X: incorrect missing Python.h message

On OS X you might get an error message like this:

SystemError: Cannot compile 'Python.h'. Perhaps you need to install python-dev|python-devel.

but maybe you actually do have them. One possible problem here is your numpy installation. Try this:

python -c "import numpy; print numpy.__file__; print numpy.__version__"

do you get back something like this:


If so, the build is getting confused with an old version of numpy that is preinstalled on your Mac. You need to manually install numpy first. We would recommend downloading the latest stable version of numpy (1.9.2 as of this edit) and installing from source using something like this:

python build
python install --user

clang: error: invalid deployment target


python develop fails because of missing capnp include

See Changes have been made (circa. December 2015) so that the nupic.core CMake build downloads and uses the appropriate Cap’n Proto library and associated capnp compiler tools.

RegionTest failure

Build error:

FAILED: RegionTest
MSG: Could not get valid spec for Region: py.TestNode


This happens when there’s a problem in linking the right version of python during build. If you know where is, you can explicitly specify the location by adding the following command-line argument to the call to cmake:


You may need to apt-get install python-devel or whatever the right ubuntu package is for the python development libs.

Build failure - cannot find glibtoolize

Make sure libtoolize is installed. On OS X, install homebrew if you don’t have it, then run brew install libtool.

cmake: command not found

Install cmake (

undeclared identifier ‘FT_GLYPH_BBOX_SUBPIXELS’

If you see this error during a build:

/System/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7/object.h:116:56: note: expanded from macro 'Py_SIZE'
#define Py_SIZE(ob)             (((PyVarObject*)(ob))->ob_size)
_imagingft.c:237:34: error: use of undeclared identifier 'FT_GLYPH_BBOX_SUBPIXELS'
error: command 'cc' failed with exit status 1

You might have a FreeType installation on your system that needs to be updated or uninstalled.

error: command ‘gcc’ failed with exit status 1

If you are on OS X, you may need to set the following environment variable.


Fatal Python error: PyThreadState_Get: no current thread

This means you have two or more versions of Python installed on your system, and there is a mismatch somewhere. The only known solution is to uninstall one or more version until you have one single version of Python on your system.

numpy version conflict error on OS X El Capitan

The following error might come up while running nupic tests after installation if you system numpy version is 1.8.

pkg_resources.VersionConflict: (numpy 1.8.0rc1 (/System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python), Requirement.parse('numpy==1.9.2'))

The required numpy version for nupic is 1.9.2. To resolve this error, before installing numpy version 1.9.2, make sure that your $PYTHONPATH is set to /Users/<yourusername>/Library/Python/2.7/lib/python/site-packages.

export PYTHONPATH=${HOME}/local/lib/python2.7/sitepackages: /Users/<yourusername>/Library/Python/2.7/lib/python/site-packages:/usr/local/lib/python2.7/site-packages:${PYTHONPATH}