CmdStan Installation

There are a few ways that you can install CmdStan. Depending on your operating system and your level of expertise, you can either:

Use the conda package management system to install a pre-built version of CmdStan along with the required dependencies. Recommended for Windows users.
Install the source code from GitHub CmdStan repository. This requires a modern C++ compiler and toolchain. See the C++ Toolchain section for further details.

Installation via `conda`

With conda, you can install CmdStan from the conda-forge channel. This will install a pre-built version of CmdStan along with the required dependencies (i.e. a C++ compiler, a version of Make, and required libraries). The conda installation is designed so one can use the R or Python bindings to CmdStan seamlessly. Additionally, it provides the command cmdstan_model to activate the CmdStan makefile from anywhere.

Note: This requires that conda has been installed already on your machine. You can either install miniconda, a free, minimal installer for conda or you can get the full Anaconda system which provides graphical installer wizards for MacOS and Windows users.

We recommend installing CmdStan in a new conda environment:

 conda create -n stan -c conda-forge cmdstan

This command creates a new conda environment named stan and downloads and installs the cmdstan package as well as CmdStan and the required C++ toolchain.

To install into an existing conda environment, use the conda install command instead of create:

 conda install -c conda-forge cmdstan

Whichever installation method you use, afterwards you must activate the new environment or deactivate/activate the existing one. For example, if you installed cmdstan into a new environment stan, run the command

 conda activate stan

By default, the latest release of CmdStan is installed. If you require a specific release of CmdStan, CmdStan versions 2.26.1 and newer can be installed by specifying cmdstan==VERSION in the install command. For example to install an earlier version of CmdStan into your current conda environment, run the following command, then re-activate the environment

conda install -c conda-forge cmdstan=2.27.0

CmdStan install location under conda

A Conda environment is a directory that contains a specific collection of Conda packages. To see the locations of your conda environments, use the command

 conda info -e

The shell environment variable CONDA_PREFIX points to the active conda environment (if any). Both CmdStan and the C++ toolchain are installed into the bin subdirectory of the conda environment directory, i.e., $CONDA_PREFIX/bin/cmdstan (Linux, MacOS), %CONDA_PREFIX%\bin\cmdstan (Windows).

Please report conda-specific install problems directly to the conda-forge issue tracker, here.

Installation from GitHub

Installation from GitHub consists of the following steps:

Verify that you have a modern C++ toolchain. See the C++ Toolchain section for details.
Download the CmdStan source code from GitHub
Build the CmdStan libraries and executables
Check the installation by compiling and running the CmdStan example model bernoulli.stan.

Downloading the source code

The GitHub source code is divided into sub-modules, each in its own repository. 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.

A CmdStan release is compressed tarfile which contains CmdStan and the Stan and math library submodules. The most recent CmdStan release is always available as https://github.com/stan-dev/cmdstan/releases/latest. A CmdStan release is versioned by major, minor, patch numbers, e.g., “2.29.2”. Please ensure you download a tarfile which is named “cmdstan-<version-number” rather than using the “Source Code” links at the bottom of the release. These are automatically generated by GitHub and do not contain the required submodules. The release tarfile unpacks into a directory named “cmdstan-”, e.g. “cmdstan-2.29.2”.

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 command will download the source code from the current development branch of CmdStan into a directory named cmdstan:

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

Throughout this manual, we refer to this top-level CmdStan source directory as <cmdstan-home>. This directory contains the following subdirectories:

directory cmdstan/stan contains the sub-module stan (https://github.com/stan-dev/stan)
directory cmdstan/stan/lib/stan_math contains the sub-module math (https://github.com/stan-dev/math)

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 (https://github.com/stan-dev/stanc3): 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:

Open a command-line terminal window and change directories to the CmdStan home directory.
Run the makefile target build which instantiates the CmdStan utilities and compiles all necessary C++ libraries.

> cd <cmdstan-home>
> make build    # on Windows use mingw32-make

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    # on Windows use mingw32-make

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.29.2 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. See these instructions for details on changing the PATH. 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 for the new environment variable settings 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.)

Checking the Stan compiler

To check that the CmdStan installation is complete and in working order, run the following series of commands from the folder which CmdStan was installed.

On Linux and macOS:

# 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

On Windows:

# compile the example
> mingw32-make examples/bernoulli/bernoulli.exe

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

# run the `bin/stansummary.exe utility to summarize parameter estimates
> bin/stansummary.exe 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.

Troubleshooting the installation

Updates to CmdStan, changes in compiler options, or updates to the C++ toolchain may result in errors when trying to compile a Stan program. Often, these problems can be resolved by removing the existing CmdStan binaries and recompiling. To do this, you must run the makefile commands from the <cmdstan-home> directory:

> cd <cmdstan-home>
> make clean-all    # on Windows use mingw32-make
> make build

Common problems

This section contains solutions to problems reported on https://discourse.mc-stan.org

Compiler error message about PCH file

To speed up compilation, the Stan makefile pre-compiles parts of the core Stan library. If these pre-compiled files are out of sync with the compiled model, the compiler will complain, e.g.:

error: PCH file uses an older PCH format that is no longer supported

In this case, clean and rebuild CmdStan, as shown in the previous section.

Windows: ‘mingw32-make’ is not recognised

If the C++ toolchain has been installed but not properly registered, then the call to mingw32-make will result in error message:

'mingw32-make' is not recognised as an internal or external command

To fix this, ensure you have followed the steps for adding the toolchain to your PATH and installing the additional utilities covered in the configuration instructions

Windows: ‘g++’ or ‘cut’ is not recognized

The CmdStan makefile uses a few shell utilities which might not be present in Windows, resulting in the error message:

'cut' is not recognized as an internal or external command,
operable program or batch file.

To fix this, ensure you have followed the steps for adding the toolchain to your PATH and installing the additional utilities covered in the configuration instructions

Spaces in paths to CmdStan or model

Both make and mingw32-make can fail when dealing with files in folders with a space somewhere in their file path. Particularly on Windows, this can be an issue when CmdStan, or the models you are trying to build, are placed in the One Drive folder.

Unfortunately, the errors created by this situation are not alwas informative. Some errors you may see are:

mingw32-make: *** INTERNAL: readdir: Invalid argument

make: *** [make/program:50: x.hpp] Error 2

If the (fully-expanded) folder path to CmdStan or the model you are trying to build contains a space, we recommend trying a different location if you encounter any issues during building.

C++ Toolchain

Compiling a Stan program requires a modern C++ compiler and the GNU Make build utility (a.k.a. “gmake”). These vary by operating system.

Linux

The required C++ compiler is g++ 4.9 3. On most systems the GNU Make utility is pre-installed and is the default make utility. There is usually a pre-installed C++ compiler as well, however, it may not be new enough. 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.

MacOS

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

Windows

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 shell ¹ and type:

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

CmdStan is known compatible with the RTools40, RTools42, and RTools43 toolchains. These require slightly different steps to configure, so please follow the appropriate steps below. All toolchains will require updating your PATH variable, See these instructions for details on changing the PATH if you are unfamiliar. The following instructions will assume that the default installation directory was used, so be sure to update the paths accordingly if you have chosen a different directory.

RTools40

RTools40 provides both a standard g++-8 toolchain and a g++-10 Universal C Runtime (UCRT) toolchain. Note the that newer g++-10 UCRT toolchain is only available for 64-bit systems, whereas the g++-8 toolchain is available for both. Additionally the UCRT is only natively supported on Windows 10 and newer, older systems will require a Microsoft update

Installation

Download the installer and complete the prompts to install.

Next, you need to add the location of the toolchain to your PATH environment variable so that it can be called from the command line. Add the following lines to your PATH:

C:\rtools40\usr\bin

# Add only one of the below
C:\rtools40\mingw32\bin   # 32-bit g++-8
C:\rtools40\mingw64\bin   # 64-bit g++-8
C:\rtools40\ucrt64\bin    # 64-bit g++-10 (UCRT)

CmdStan additionally needs the mingw32-make utility, which you can install using RTools. Navigate to the installation directory (e.g., C:\rtools40) and launch the msys2.exe file. Execute the appropriate command below to install mingw32-make for your selected toolchain:

pacman -Sy mingw-w64-i686-make            # 32-bit g++-8
pacman -Sy mingw-w64-x86_64-make          # 64-bit g++-8
pacman -Sy mingw-w64-ucrt-x86_64-make     # 64-bit g++-10 (UCRT)

RTools42 & RTools43

Both RTools42 & RTools43 provide 64-bit UCRT toolchains, where RTools42 provides g++-10 and RTools43 provides g++-12. The installation/configuration is identical for both toolchains.

Installation

Download the installer for your preferred toolchain and complete the prompts for installation:

Next, you need to add the toolchain directory to your PATH variable. Add the appropriate lines from below:

# RTools42
C:\rtools42\usr\bin
C:\rtools42\ucrt64\bin

# RTools43
C:\rtools43\usr\bin
C:\rtools43\ucrt64\bin

Next, you need to install the mingw32-make utility and some additional compiler dependencies. Navigate to the installation directory of the toolchain and launch the msys2.exe file. Execute the below commands to install the needed dependencies:

pacman -Sy mingw-w64-ucrt-x86_64-make mingw-w64-ucrt-x86_64-gcc

32-bit Builds

CmdStan defaults to a 64-bit build. On a 32-bit operating system, you must specify the make variable BIT=32 as part of the make command, described in the next section.

Using GNU Make

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.

The conda-forge cmdstan package provides a solution to this problem via cmdstan_model command which lets you run the CmdStan makefile from anywhere to compile a Stan model.

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).

To call Make, you invoke the utility name, either make or mingw32-make, followed by, in order:

zero or more Make program options, then specify any Make variables as a series of
zero of more Make variables, described below
zero or more target names; the set of names is determined by the Makefile rules.

make <flags> <variables> <targets>

Makefile Variables

Make targets can be preceded by any number of Makefile variable name=value pairs. For example, to compile ../my_dir/my_program.stan for an OpenCL (GPU) machine, set the makefile variable STAN_OPENCL to TRUE:

> make STAN_OPENCL=TRUE ../my_dir/my_program    # on Windows use mingw32-make

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. For example, if you are working on a 32-bit machine, you would put the line BIT=32 into the file <cmdstan-home>/make/local so that all CmdStan programs and Stan models compile properly.

The complete set of Makefile variables can be found in file <cmdstan-home>/cmdstan/stan/lib/stan_math/make/compiler_flags.

Make Targets

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

> make    # on Windows use mingw32-make
--------------------------------------------------------------------------------
CmdStan v2.33.1 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), 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.
    STANC3_VERSION: When set, uses that tagged version specified; otherwise, downloads
      the nightly version.
    STAN_CPP_OPTIMS: Turns on additonal compiler flags for performance.
    STAN_NO_RANGE_CHECKS: Removes the range checks from the model for performance.


  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

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

Footnotes

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.↩︎

CmdStan Installation

Installation via conda

CmdStan install location under conda

Installation from GitHub

Downloading the source code

Building CmdStan

Checking the Stan compiler

Troubleshooting the installation

Common problems

C++ Toolchain

Linux

MacOS

Windows

RTools40

Installation

RTools42 & RTools43

Installation

Using GNU Make

Footnotes

Installation via `conda`