This is an old version, view current version.

1 CmdStan Installation

To install CmdStan you need:

  • A modern C++11 compiler. Supported versions are
    \(\tiny\bullet\) Linux: g++ 4.9.3 or clang 6.0
    \(\tiny\bullet\) macOS: the XCode version of clang
    \(\tiny\bullet\) Windows: g++ 8.1 (available with RTools 4.0) is recommended; alternatively, g++ 4.9.3 (available with RTools 3.5).

  • The GNU-Make utility program or the Windows equivalent mingw32-make. On macOS, this is part of the XCode command line tools installed via command xcode-select --install. On Windows, mingw32-make is installed as part of RTools: https://cran.rstudio.com/bin/windows/Rtools/.

  • The CmdStan C++ source code and libraries.
    The most recent CmdStan release is available as a single compressed tarfile containing all of the CmdStan tools and the Stan and math libraries from GitHub: https://github.com/stan-dev/cmdstan/releases/latest or you can clone the GitHub repo.

The CmdStan release unpacks into a directory called cmdstan-<version> where the version string consists of the major.minor.patch version numbers, e.g. cmdstan-2.23.0. Cloning CmdStan from GitHub creates a directory simply called cmdstan. Throughout this manual, we refer to this top-level CmdStan source directory as <cmdstan-home>.

1.1 Installing the C++ Toolchain

The C++ toolchain consists of a modern C++ compiler and the GNU-Make utility, described in greater detail in the following section.

1.1.1 Linux: g++ and make

On Linux, the C++ compiler command g++ and the GNU-Make command is make. These are often installed by default. To check, run commands:

g++ --version
make --version

If these are at least at g++ version 4.9.3 or later and make version 3.81 or later, no additional installations are necessary. It may still be desirable to update the C++ compiler g++, because later versions are faster.

To install the latest version of these tools (or upgrade an older version), use the following commands or their equivalent for your distribution, install via the commands:

sudo apt install g++
sudo apt install make

If you can’t run sudo, you will need to ask your sysadmin or cluster administrator to install these tools for you.

1.1.2 MacOS: clang++ and make

To install a C++ development environment on a Mac, use Apple’s Xcode development environment https://developer.apple.com/xcode/.

From the Xcode home page View in Mac App Store.

  • From the App Store, click Install, enter an Apple ID, and wait for Xcode to finish installing.
  • Open the Xcode application, click top-level menu Preferences, click top-row button Downloads, click button for Components, click on the Install button to the right of the Command Line Tools entry, then wait for it to finish installing.
  • Click the top-level menu item Xcode, then click item Quit Xcode to quit.

To test, open the Terminal application and enter:

clang++ --version
make --version

If you have installed XCode, but don’t have make, you can install the XCode command-line tools via command:

xcode-select --install

Note MacOS installations may include old version of the g++ compiler which is a version 4.2.1. CmdStan requires g++ at 4.9.3 or later. Trying to install later versions of g++ using homebrew or macports is no longer recommended; use the XCode toolchain.

1.1.3 Windows: g++ and mingw32-make

The Windows toolchain consists of programs g++, the C++ compiler, and mingw32-make, the GNU-Make utility. To check if these are present, open a command shell1 and type:

g++ --version
mingw32-make --version

Rtools C++ Development Environment

The simplest way to install a full C++ build environment that will work for CmdStan is to use the Rtools package designed for R developers on Windows (even if you don’t plan to use R).

If you don’t have RTools, the latest version is Rtools40 (released April 2020) which can be downloaded from:

After installation is complete, you need to perform one more step: you need to add the location of the Rtools compiler and make utilities to the PATH environment variable. If you have Rtools40, these should be:

C:\RTools\RTools40\usr\bin
C:\RTools\RTools40\mingw64\bin

If you have and earlier version of RTools, e.g., RTools 3.6, use RTools36 istead of RTools40 in the above paths. See these instructions for details on changing the PATH.

32-bit Builds

CmdStan defaults to a 64-bit build. On a 32-bit operating system, include BIT=32 in CmdStan make/local file described in the next section.

1.2 GNU-Make Utility

CmdStan relies on the GNU-make utility to build both the Stan model executables and the CmdStan tools.

GNU-Make builds executable programs and libraries from source code by reading files called Makefiles which specify how to derive the target program. A Makefile consists of a set of recursive rules where each rule specifies a target, its dependencies, and the specific operations required to build the target. Specifying dependencies for a target provides a way to control the build process so that targets which depend on other files will be updated as needed only when there are changes to those other files. Thus Make provides an efficient way to manage complex software.

The CmdStan Makefile is in the <cmdstan-home> directory and is named makefile. This is one of the default GNU Makefile names, which allows you to omit the -f makefile argument to the Make command. Because the CmdStan Makefile includes several other Makefiles, Make only works properly when invoked from the <cmdstan-home> directory; attempts to use this Makefile from another directory by specifying the full path to the file makefile won’t work. For example, trying to call Make from another directory by specifying the full path the the makefile results in the following set of error messages:

make -f ~/github/stan-dev/cmdstan/makefile
/Users/mitzi/github/stan-dev/cmdstan/makefile:58: make/stanc: No such file or directory
/Users/mitzi/github/stan-dev/cmdstan/makefile:59: make/program: No such file or directory
/Users/mitzi/github/stan-dev/cmdstan/makefile:60: make/tests: No such file or directory
/Users/mitzi/github/stan-dev/cmdstan/makefile:61: make/command: No such file or directory
make: *** No rule to make target `make/command'.  Stop.

Makefile syntax allows general pattern rules based on file suffixes. Stan programs must be stored in files with suffix .stan; the CmdStan makefile rules specify how to transform the Stan source code into a binary executable. For example, to compile the Stan program my_program.stan in directory ../my_dir/, the make target is ../my_dir/my_program or ../my_dir/my_program.exe (on Windows).

Make is invoked with a list of target names which can be preceded by zero or more Makefile variable name=value pairs. For example to compile ../my_dir/my_program.stan for an OpenCL (GPU) machine, the makefile variable STAN_OPENCL is set to TRUE:

> make STAN_OPENCL=TRUE ../my_dir/my_program

Makefile variables can also be set by creating a file named local in the CmdStan make subdirectory which contains a list of <VARIABLE>=<VALUE> pairs, one per line. The complete set of Makefile variables can be found in file cmdstan/stan/lib/stan_math/make/compiler_flags.

When invoked without any arguments at all, Make prints a help message:

> make
--------------------------------------------------------------------------------
CmdStan v2.23.0 help

  Build CmdStan utilities:
    > make build

    This target will:
    1. Install the Stan compiler bin/stanc from stanc3 binaries.
    2. Build the print utility bin/print (deprecated; will be removed in v3.0)
    3. Build the stansummary utility bin/stansummary
    4. Build the diagnose utility bin/diagnose
    5. Build all libraries and object files compile and link an executable Stan program

    Note: to build using multiple cores, use the -j option to make, e.g., 
    for 4 cores:
    > make build -j4


  Build a Stan program:

    Given a Stan program at foo/bar.stan, build an executable by typing:
    > make foo/bar

    This target will:
    1. Install the Stan compiler (bin/stanc or bin/stanc2), as needed.
    2. Use the Stan compiler to generate C++ code, foo/bar.hpp.
    3. Compile the C++ code using cc . to generate foo/bar

  Additional make options:
    STANCFLAGS: defaults to "". These are extra options passed to bin/stanc
      when generating C++ code. If you want to allow undefined functions in the
      Stan program, either add this to make/local or the command line:
          STANCFLAGS = --allow_undefined
    USER_HEADER: when STANCFLAGS has --allow_undefined, this is the name of the
      header file that is included. This defaults to "user_header.hpp" in the
      directory of the Stan program.
    STANC2: When set, use bin/stanc2 to generate C++ code.


  Example - bernoulli model: examples/bernoulli/bernoulli.stan

    1. Build the model:
       > make examples/bernoulli/bernoulli
    2. Run the model:
       > examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R
    3. Look at the samples:
       > bin/stansummary output.csv


  Clean CmdStan:

    Remove the built CmdStan tools:
    > make clean-all

--------------------------------------------------------------------------------

1.3 Clone the GitHub CmdStan Repository

This section can be skipped if you want to build CmdStan using the release tarfile, which contains all source files an libraries needed to build CmdStan. However, if you wish to use the current (stable) development version of CmdStan, you must clone the CmdStan GitHub repo.

The CmdStan repo contains just the cmdstan module; the Stan inference engine algorithms and Stan math library functions are specified as submodules and stored in the GitHub repositories stan and math, respectively. By cloning the CmdStan repository with argument --recursive, Git automatically initializes and updates each submodule in the repository, including nested submodules if any of the submodules in the repository have submodules themselves.

The following sequence of commands will check out the current CmdStan develop branch on GitHub and assemble and build the command line interface and supporting libraries:

> git clone https://github.com/stan-dev/cmdstan.git --recursive
> cd cmdstan
> make build

The resulting set of directories should have the same structure as the release:

1.4 Building CmdStan

Building CmdStan involves preparing a set of executable programs and compiling the command line interface and supporting libraries. The CmdStan tools are:

  • stanc: the Stan compiler (translates Stan language to C++).

  • stansummary: a basic posterior analysis tool. The stansummary utility processes one or more output files from a run or set of runs of Stan’s HMC sampler. For all parameters and quantities of interest in the Stan program, stansummary reports a set of statistics including mean, standard deviation, percentiles, effective number of samples, and \(\hat{R}\) values.

  • diagnose: a basic sampler diagnostic tool which checks for indications that the HMC sampler was unable to sample from the full posterior.

CmdStan releases include pre-built binaries of the Stan language compiler : bin/linux-stanc, bin/mac-stanc and bin/windows-stanc. The CmdStan makefile build task copies the appropriate binary to bin/stanc. For CmdStan installations which have been cloned of downloaded from the CmdStan GitHub repository, the makefile task will download the appropriate OS-specific binary from the stanc3 repository’s nightly release.

Steps to build CmdStan:

> cd <cmdstan-home>
> make build

If your computer has multiple cores and sufficient ram, the build process can be parallelized by providing the -j option. For example, to build on 4 cores, type:

> make -j4 build

When make build is successful, the directory <cmdstan-home>/bin/ will contain the executables stanc, stansummary, and diagnose (on Windows, corresponding .exe files) and the final lines of console output will show the version of CmdStan that has just been built, e.g.:

--- CmdStan v2.23.0 built ---

Warning: The Make program may take 10+ minutes and consume 2+ GB of memory to build CmdStan.

Windows only: CmdStan requires that the Intel TBB library, which is built by the above command, can be found by the Windows system. This requires that the directory <cmdstan-home>/stan/lib/stan_math/lib/tbb is part of the PATH environment variable. To permanently make this setting for the current user, you may execute:

> mingw32-make install-tbb

After changing the PATH environment variable, you must open an new shell in order to these setting to take effect. (This is not necessary on Mac and Linux systems because they can use the absolute path to the Intel TBB library when linking into Stan programs.)

1.5 Trouble-shooting the installation

To check that the CmdStan installation is complete and in working order, run the following series of commands:

# compile the example
> make examples/bernoulli/bernoulli

# fit to provided data (results of 10 trials, 2 out of 10 successes)
> ./examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.json

# default output written to file `output.csv`,
# default num_samples is 1000, output file should have approx 1050 lines
> ls -l output.csv

# run the `bin/stansummary utility to summarize parameter estimates
> bin/stansummary output.csv

The sample data in file bernoulli.json.data specifies 2 out of 10 successes, therefore the range mean(theta)\(\pm\)sd(theta) should include 0.2.

Updates to CmdStan or changes in compiler options may result in errors when trying to compile a Stan program. In some cases, these can be resolved by removing the existing CmdStan build and recompiling. The Makefile target clean-all should be run before rebuilding CmdStan:

> make clean-all
> make build

  1. To open a Windows command shell, first open the Start Menu, (usually in the lower left of the screen), select option All Programs, then option Accessories, then program Command Prompt. Alternatively, enter [Windows+r] (both keys together on the keyboard), and enter cmd into the text field that pops up in the Run window, then press [Return] on the keyboard to run.↩︎