MacOS Installation

Pete Schultz edited this page Jun 15, 2018 · 10 revisions

This is a tutorial on getting PetaVision installed and running on macOS, assuming you have a clean installation of macOS. You will need an admin account (for installing packages with sudo). Tested on macOS 10.12.6 (Sierra). If you have an NVIDIA card and upgrade to Sierra, you will need to reinstall CUDA.


  • macOS
  • sudo access

Required installations

  • Xcode and Xcode command line tools
  • Homebrew

Optional installations

  • OpenMPI (to take advantage of MPI parallelization)
  • CUDA and cuDNN (to take advantage of CUDA GPU acceleration)
  • A C/C++ compiler with OpenMP capabilities (to take advantage of OpenMP parallelization)
  • Octave (to use the m-files in the mlab directory for analysis)


Xcode is needed to install Homebrew and C/C++ compilers. Here's how to get it.

  • Go to the Apple App Store and search for Xcode
  • Click 'GET', then 'INSTALL'. Put in your Apple ID information
  • After it's installed, we need to accept the Xcode license.
    • Run the Xcode application
    • Follow the onscreen prompt until you see the main Xcode screen
    • Exit Xcode
  • We also need command line tools for Xcode
    • Go into a terminal and execute the following command
xcode-select --install
  • Follow the onscreen prompt to install command line tools.


Homebrew is a package manager for macOS, which we will use for many of PetaVision's dependencies. Additional information can be found at To install homebrew:

ruby -e "$(curl -fsSL"


brew update
brew install cmake

# optionally, to install wget (needed if a Movie layer will get frames from URLs):
brew install wget

# optionally, to install OpenMPI:
brew install open-mpi

# optionally, to install Octave using homebrew
brew cask install xquartz
brew install gnuplot --with-x11
brew tap homebrew/science
brew install octave --build-from-source

Note: if you install octave, the command brew install octave --build-from-source can take some time to execute. However, without the build-from-source option, the octave binary that gets downloaded hardcodes specific versions of some dependencies, and in some cases the hardcoded version is out-of-date.

# optionally, to use mermaid-based tool for drawing diagrams of params files:
brew install npm
npm install -g phantomjs
npm install -g mermaid@7.0.0

Note: as of this writing (July 2017), the most recent version of mermaid, 7.0.3, has a bug in drawing arrowheads. Accordingly, be sure to specify the version 7.0.0.

If you want to take advantage of OpenMP threading, see below.

OpenMP/CUDA incompatibility on the Mac.

OpenMP and CUDA are optional technologies that add parallelization to the code. OpenMP implements parallel threading on the CPU, and is useful on machines with multiple cores. CUDA allows the use of an NVIDIA GPU. In principle it should be possible to use both of these at different points in the same program; however on the Mac, NVIDIA's compiler insists on using a compiler that is incompatible with OpenMP. Therefore, you can use one or the other (or neither) of these but not both.

OpenMP-compatible Clang (optional)

Currently (macOS Sierra 10.12.5 and Xcode 8.3.3), the version of Clang installed by Xcode does not support OpenMP. The program installed by Xcode as gcc is also Clang, not GNU-GCC (as can be verified by running gcc --version). To make use of the OpenMP threading in PetaVision you will need an OpenMP-compatible compiler. Clang versions 3.7.0 and later support OpenMP, but Xcode is still behind this version. Here are instructions to download the most recent version of clang.

Install the OMP-compatible version of Clang

brew install llvm
cd /usr/local/lib
ln -s ../Cellar/llvm/5.0.0/lib/libiomp5.dylib libiomp5.dylib

(As of this writing, homebrew has llvm version 5.0.0. Update the directory after llvm/ as necessary.)

The OpenMP-compatible clang compilers are in the directory /usr/local/opt/llvm/bin, as clang and clang++. To use them instead of the Xcode-supplied clang and clang++ from the command line, you may want to add this directory to your PATH environment variable.

Make a note that when you run ccmake, below, you will need to set the C++ and C compilers to /usr/local/opt/llvm/bin/clang++ and /usr/local/opt/llvm/bin/clang.

CUDA and NVIDIA Driver (optional):

To take advantage of CUDA/cuDNN GPU acceleration your Macintosh needs to have an NVIDIA card with compute capabilities 3.0 or above. To find which video card you have, go to "About This Mac" under the Apple menu, select "System Report..." and then Graphics/Displays in the Hardware section. Check at to see if your video card supports CUDA. NVIDIA drivers are included with the cuda download. To install cuda:

  • Go to
  • Select Mac OS X, and then your version of macOS and download the local installer .dmg
  • If the .dmg does not automatically open, double-click the .dmg file to mount the CUDAMacOSXInstaller disk.
  • Open the CUDAMacOSXInstaller/CUDAMacOSXInstaller app on that disk and follow the onscreen instructions.
  • Open the downloaded .pkg file and follow the onscreen instructions. On the Select Packages To Install page, make sure to select cuda driver and cuda toolkit.

Go to and click Download at the bottom. Register with NVIDIA developers if need be, and wait for confirmation. Download the OS X version of cuDNN (Alternatively, if you have access to NMC's compneuro, grab it from here: /nh/compneuro/Data/cuDNN-macOS/)

On macOS, NVIDIA's nvcc compiler insists on a single specific version of the Xcode-supplied compiler. As of this writing, the most recent version of CUDA, version 9.0, requires Xcode version 8.3.3; but Apple has released Xcode 9.0.1. If your Xcode version is not 8.3.3, you will need an Apple Developer account to download an older version of Xcode from Click on the search result to reveal a link to Xcode8.3.3.xip and download this file (4.2GB). If you downloaded the file to a machine other than your mac, you will need to transfer it to the mac before opening it. Open the archive by double-clicking it in the mac's file system, and then rename the resulting to

Move into the /Applications folder. Then from a terminal, run the commands

sudo xcode-select --switch /Applications/
sudo xcode-select --install

If you run into version incompatibilities, we have found the following specific versions to work:

  • macOS Sierra 10.12.6
  • CUDA driver version 9.0.197 (shown in the CUDA Preferences pane in System Preferences)
  • GPU driver version 10.17.5 355.10.05.45f01 (shown in the CUDA Preferences pane in System Preferences)
  • cuDNN version 7.0 for CUDA 9.0.

Checking Out and Installing PetaVision:

cd ${HOME}
git clone

To build PetaVision and run the system tests, please see this page.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.