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. We recommend using the miniforge distribution.

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

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

> 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
> wc -l output.csv

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

On Windows:

# compile the example
> 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
> 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: ‘g++’, ‘make’, 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

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:

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 check if you already already have an appropriate toolchain installed, open the Terminal application and enter:

clang++ --version
make --version

If either of these commands prints the message command not found, you will need to install Xcode’s command line tools.

Open the Terminal application and enter:

xcode-select --install

Select “Install” in the window that opens.

After the installation completes, you can double check that installation was successful by reopening the Terminal and running:

clang++ --version
make --version

You can read more about Xcode on its site: https://developer.apple.com/xcode/

We don’t recommend trying to use the GNU C++ compiler, available via Homebrew, based on the number of reports of installation difficulties from Mac users on GitHub as well as the Stan forums.

Windows

The Windows toolchain consists of programs g++, the C++ compiler, and make, the GNU Make utility. To check if these are present, open a command shell [^1] and type:

g++ --version
make --version

CmdStan is known compatible with the RTools44 toolchain. The toolchain 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.

RTools44

All required utilities (e.g., make, g++) for compiling and running CmdStan models on Windows are provided by the RTools44 toolchain from the R Project. Installation steps are provided below, and for more technical details on the toolchain refer to the R Project documentation.

The R Project provides RTools44 for both Intel/AMD 64-bit (x86_64) and ARM 64-bit (aarch64) systems. If you are unsure which to use, then you can check by going to the Windows Settings, selecting the ‘System’ menu and then the ‘About’ option. If the ‘System Type’ field lists ‘ARM-based processor’, then you should follow the ARM64 instructions below.

Note that the toolchain is only available for 64-bit systems, and uses the new Universal C Runtime (UCRT). UCRT is only natively supported on Windows 10 and newer, older systems will require a Microsoft update.

Installation - Intel/AMD 64-bit (x86_64)

Download the installer and complete the prompts for installation:

If the above link no longer works, navigate here and download the latest file which is named rtools44-xxxx-yyyy.exe (xs and ys will be different version numbers over time).

Next, you need to add the toolchain directory to your PATH variable:

C:\rtools44\usr\bin
C:\rtools44\x86_64-w64-mingw32.static.posix\bin
Installation - ARM 64-bit (arm64/aarch64)

Download the installer and complete the prompts for installation:

If the above link no longer works, navigate here and download the latest file which is named rtools44-aarch64-xxxx-yyyy.exe (xs and ys will be different version numbers over time).

Next, you need to add the toolchain directory to your PATH variable:

C:\rtools44-aarch64\usr\bin
C:\rtools44-aarch64\aarch64-w64-mingw32.static.posix\bin

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, 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

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, to get the same effect as the above command every time, you would put the line STAN_OPENCL=TRUE into the file <cmdstan_home>/make/local.

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

--------------------------------------------------------------------------------
Back to top