CmdStanPy is a pure-Python3 package which wraps CmdStan, the command-line interface to Stan which is written in C++. Therefore, in addition to Python3, CmdStanPy requires a modern C++ toolchain in order to build and run Stan models. There are several ways to install CmdStanPy and the underlying CmdStan components.
You can download CmdStanPy, CmdStan, and the C++ toolchain from conda-forge.
If you want the current development version, you can clone the GitHub CmdStanPy repository.
If you install CmdStanPy from PyPI or GitHub you will need to install CmdStan as well, see section CmdStan Installation below.
Conda: install CmdStanPy, CmdStan, C++ toolchain#
If you use conda, you can install CmdStanPy and the underlying CmdStan components from the conda-forge repository via the following command:
conda create -n stan -c conda-forge cmdstanpy
This command creates a new conda environment named
downloads and installs the
as well as CmdStan and the required C++ toolchain.
To install into an existing environment, use the conda
install command instead of
conda install -c conda-forge cmdstanpy
Whichever installation method you use, afterwards you must
activate the new environment or deactivate/activate the existing one.
For example, if you installed cmdstanpy into a new environment
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.
Versions before 2.26.1 are not available from conda
but can be downloaded from the CmdStan
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),
PyPI: install package CmdStanPy#
CmdStan can also be installed from PyPI via URL: https://pypi.org/project/cmdstanpy/ or from the
command line using
pip install --upgrade cmdstanpy
The optional packages are
xarray, an n-dimension labeled dataset package which can be used for outputs
To install CmdStanPy with all the optional packages:
pip install --upgrade cmdstanpy[all]
GitHub: install from the CmdStanPy repository#
To install the current develop branch from GitHub:
pip install -e git+https://github.com/stan-dev/cmdstanpy@develop#egg=cmdstanpy
Note for PyStan & RTools users: PyStan and CmdStanPy should be installed in separate environments if you are using the RTools toolchain (primarily Windows users). If you already have PyStan installed, you should take care to install CmdStanPy in its own virtual environment.
Jupyter notebook users: If you intend to run CmdStanPy from within a Jupyter notebook, you may need to install the ipywidgets. This will allow for progress bars implemented using the tqdm to display properly in the browser. For further help on Jupyter notebook installation and configuration , see ipywidgets installation instructions and this tqdm GitHub issue.
If you have installed CmdStanPy from PyPI or Github,
you must install CmdStan.
The recommended way to do so is via the
If you installed CmdStanPy with conda, CmdStan and the C++ toolchain,
both CmdStan and the C++ toolchain are installed into directory
and you don’t need to do any further installs.
C++ Toolchain Requirements#
To compile a Stan program requires a modern C++ compiler and the GNU-Make build utility. 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
There is usually a pre-installed C++ compiler as well, but not necessarily new enough.
MacOS The Xcode and Xcode command line tools must be installed. Xcode is available for free from the Mac App Store.
To install the Xcode command line tools, run the shell command:
Windows We recommend using the RTools 4.0 toolchain
which contains a
g++ 8 compiler and
Mingw, the native Windows equivalent of the GNU-Make utility.
This can be installed allong with CmdStan when you invoke the function
CmdStanPy provides the function
downloads CmdStan from GitHub and builds the CmdStan utilities.
It can be can be called from within Python or from the command line.
The default install location is a hidden directory in the user
.cmdstan. This directory will be created by the install script.
On Windows, the
compiler option will install the C++ toolchain.
import cmdstanpy cmdstanpy.install_cmdstan() cmdstanpy.install_cmdstan(compiler=True) # only valid on Windows
From the command line on Linux or MacOSX
install_cmdstan ls -F ~/.cmdstan
install_cmdstan --compiler dir "%HOME%/.cmdstan"
-i) can be used to run
the installation script in an interactive prompt. This will ask
you about the various options to the installation script, with
reasonable defaults set for all questions.
The named arguments:
-d <directory> and
can be used to override these defaults:
install_cmdstan -d my_local_cmdstan -v 2.27.0 ls -F my_local_cmdstan
Alternate Linux Architectures#
CmdStan can be installed on Linux for the following non-x86 architectures:
CmdStanPy will do its best to determine which of these is applicable for your
machine when running
install_cmdstan. If the wrong choice is made, or if you
need to manually override this, you can set the
CMDSTAN_ARCH environment variable
to one of the above options, or to “false” to use the standard x86 download.
If you with to install CmdStan yourself, follow the instructions in the CmdStan User’s Guide.
Locating the CmdStan installation directory#
CmdStanPy uses the environment variable
CMDSTAN to register the CmdStan installation location.
If you use conda to install CmdStanPy, CmdStan is installed into location
%CONDA_PREFIX%\bin\cmdstan(Windows) and the environment variable
CMDSTANis set accordingly.
If no environment variable
CMDSTANis set, CmdStanPy will try to locate a CmdStan installation in the default install location, which is a directory named
If you have installed CmdStan from a GitHub release or by cloning the CmdStan repository,
you will need to set this location, either via the
CMDSTAN environment variable,
or via the CmdStanPy command
from cmdstanpy import cmdstan_path, set_cmdstan_path set_cmdstan_path(os.path.join('path','to','cmdstan')) cmdstan_path()