CmdStanPy is a pure-Python3 package, but it relies on CmdStan for all of its functionality. There are several ways to install CmdStan and CmdStanPy, which depend on the kind of user you are.
Conda users (Recommended)¶
We recommend creating a new environment for CmdStan[Py]:
conda create -n cmdstan -c conda-forge cmdstanpy
but installation is possible in an existing environment (Note: you must re-activate the environment after running this command!):
conda install -c conda-forge cmdstanpy
These commands will install CmdStanPy, CmdStan, and the
required compilers for using CmdStan on your system inside
a conda environment. To use them, run
conda activate cmdstan,
or whichever name you used for your environment (following
Note that CmdStan is only available on conda for versions
2.26.1 and newer. If you require an older version, you must use
one of the following methods to install it. If you require a
version of CmdStan newer than 2.26.1”, but not the latest,
you can install it in the standard conda way by specifying
cmdstan==VERSION in the install command.
Pip (non-Conda) users¶
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]
To install the current develop branch from GitHub:
pip install -e git+https://github.com/stan-dev/cmdstanpy@/develop#egg=cmdstanpy
If you install CmdStanPy from GitHub,
you must install CmdStan. The recommended way for Pip users
to do so is via the
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: CmdStanPy can display progress bars during sampling as well as during the CmdStan build process; these are implemented using the tqdm package, which uses the ipywidgets package in order to update the browser display. For further help on installation and configuration, see ipywidgets installation instructions and this tqdm GitHub issue.
CmdStanPy requires an installed C++ toolchain consisting of a modern C++ compiler and the GNU-Make utility.
Windows: CmdStanPy provides the function
Linux: install g++ 4.9.3 or clang 6.0. (GNU-Make is the default
maxOS: install XCode and Xcode command line tools via command: xcode-select –install.
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.
import cmdstanpy cmdstanpy.install_cmdstan()
From the command line on Linux or MacOSX
install_cmdstan ls -F ~/.cmdstan
python -m cmdstanpy.install_cmdstan dir "%HOME%/.cmdstan"
The named arguments: -d <directory> and -v <version> can be used to override these defaults:
install_cmdstan -d my_local_cmdstan -v 2.27.0 ls -F my_local_cmdstan
If you with to install CmdStan yourself, follow the instructions in the CmdStan User’s Guide.
Post Installation: Setting Environment Variables¶
The default for the CmdStan installation location
is a directory named
.cmdstan in your
$HOME directory. 1
If you have installed CmdStan in a different directory,
then you can set the environment variable
CMDSTAN to this
location and it will be picked up by CmdStanPy. Note: This is done
for you if you installed via
conda, as cmdstan will be installed
bin/ subfolder of the environment directory.
The CmdStanPy commands
get and set this environment variable:
from cmdstanpy import cmdstan_path, set_cmdstan_path oldpath = cmdstan_path() set_cmdstan_path(os.path.join('path','to','cmdstan')) newpath = cmdstan_path()
To use custom
from cmdstanpy import set_make_env set_make_env("mingw32-make.exe") # On Windows with mingw32-make
In very early versions, this hidden directory was named