Procedure of How to build Numenta NuPIC on MacOS X Mavericks

This article is basically identical to the original procedure of how to build Numenta NuPIC on MacOS X Mavericks and reviews the whole build and installation process.

This follows the procedure, which is listed on “Getting Started wiki” at nupic repository. The nupic repository is located at numenta's account of Github.

How to execute NuPIC is written at the section of “Running NuPIC on OS X.”


  • Git (pre-installed in Mac OS X Mavericks)
  • Python (pre-installed in Mac OS X Mavericks)
  • GCC or Clang (pre-installed in Mac OS X Mavericks)
  • CMake (needed to be newly installed in Mac OS X Mavericks, details are explained later)

Build Procedure

  1. OS
    Please update to OS X 10.9 Mavericks if your Mac is not running other than Mac OS X 10.9.
    It is very difficult to build NuPIC on earlier version of Mac OS X other than Mac OS X 10.9. Mac OS X 10.9 or later is recommended. In this article Mac OS X 10.9.2 is used for replicating the procedure.

  2. Build Tools
    Install XCode 5 or later.
    Download it from App Store, and install it. Then, at Application Menu of XCode, please select,
    Xcode > Open Developer Tool > More Developer Tools
    Then, as web pages of “Downloads for Apple Developers” is open, install the newest version of “Command Line Tools (OS X Mavericks) for Xcode.

    The versions of tools, which are used here are:
    Xcode 5.0.2
    Command Line Tools (OS X Mavericks) for Xcode Late October 2013

  3. homebrew
    To install other packages, which are required for the build procedure, install homebrew. To use home, Install the packages shown below.

    CMake is available at its web page, and you may download its dmg file and install it to OS X 10.9. However, if the security setting of your OS X 10.9 remains in the default, you can only run Apps, which you can purchase and download from Apple App Store, and you cannot use individually downloaded applications. Please choose either to change the security setting of OS X 10.9 or to use homebrew for installing CMake.

    In this article, homebrew is employed for installing CMake and recommended.

    To install homeberw, please open up Terminal, type in the command line below.
    $ ruby -e “$(curl -fsSL”

    As the installation process of homebrew is completed without any errors, please check it update and run a diagnostic test.
    $ brew update
    $ brew doctor

    “$ brew update” is for checking any updates, and “$brew doctor” performs a diagnostic test. Then, its update is completed and any issues are not found, please install the packages listed above.
    $ brew install automake libtool cmake

  4. Downloading Source Code
    Checkout by git. A working directory "work" is created, and the downloaded source code is stored at this working directory.
    If you wish to contribute to NuPIC, please create own github.
    $ cd ~
    $ mkdir work
    $ cd work
    $ git clone

  5. Environment Variable
    Store the environment variables, which are required for the build process and execution of NuPIC. Write down the environment variables into “.Profile”. Then, open up this file from Terminal with the command shown below. Make sure that what you have written is correctly stored in the file.
    $ printenv 
    If you do not like storing these information variable in “.profile” file. You can write down these environment variables in any file. In such case, you have to do “source” every time and load to your shell before build and execute NuPIC.
    # Target source/repo path (where you cloned the repo). Default to $PWD
    export NUPIC=~/dev/nupic
    # NTA installation path
    export NTA=$NUPIC/nta/eng
    # Convenience variable for temporary build file
    export BUILDLIR=/tmp/ntabuild
    # Number of jobs to run in parallel (Optional)
    export MK_JOBS=3
    # Set up the rest of the necessary env variables. Must be after
    # setting $NTA.
    source $NUPIC/

  6. pip
    pip is a tool that manages Python Packages. Install pip.
    $ sudo easy_install pip

  7. Installing Python Library
    To use pip, install the python library, which is necessary for NuPIC.
    $ sudo pip install -r $NUPIC/external/common/requirements.txt
    According to Running NuPIC on OS X if you install pip 1.5 or greater, you should apply the command shown below, which does have options. However, as far as tested here, the original command works fine.
    $ sudo pip install ―allow-all-external ―allow-unverified PILL ―allow-unverified psutil -r $NUPIC/external/common/requirements.txt

  8. Build NuPIC
    Execute the build script. If the messages shown below appears on Terminal, the build process is successfully completed.
    $ $NUPIC/
    Stdout redirected to; /Users/otsuka/work/nupic/build_system/stdout.txt
    Build successful.


After the build process is completed, NuPIC is tested for its correctly execution.

  • C++ Test
    $ cd $NTA/bin

    $ htmtest
    ... Skip

    $ testeverything
    ... Skip
    * Numenta Unit Test summary
    * Total categories = 39
    * Total tests = 2252
    * Total passed   = 2252
    * Total disabled = 0
    * Total failed   = 0
    * Total critical failures = 0
    * Success rate = 100
  • Python Unit Test

    $ cd $NUPIC

    $ $NUPIC/
    ============================= test session starts ==============================
    platform darwin -- Python 2.7.5 -- pytest-2.4.2 -- /usr/bin/python
    plugins: cov, xdist
    collected 697 items / 2 skipped 
    … Skip
    =================== 687 passed, 12 skipped in 150.86 seconds ===================


Even though the build process uses CMake, the build precess encounters problems when it is executed by GUI of XCode.

Versions of Tools

$ python -V
Python 2.7.5

$ pip -V
pip 1.5.4 from /Library/Python/2.7/site-packages/pip-1.5.4-py2.7.egg (python 2.7)

$ clang -v
Apple LLVM version 5.0 (clang-500.2.79) (based on LLVM 3.3svn)
Target: x86_64-apple-darwin13.1.0
Thread model: posix

$ brew ―version

$ brew list
autoconf     automake     cmake     libtool

Revision History

  • 2014/04/21 This article is initially published

Front page   Edit Freeze Diff Backup Upload Copy Rename Reload   New List of pages Search Recent changes   RSS of recent changes
Last-modified: 2014-04-21 (Mon) 07:10:34 (2711d)