Installation

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.

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:

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 install_cmdstan function described below

Note

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.

Installing CmdStan

Prerequisites

CmdStanPy requires an installed C++ toolchain consisting of a modern C++ compiler and the GNU-Make utility.

  • Windows: CmdStanPy provides the function install_cxx_toolchain

  • Linux: install g++ 4.9.3 or clang 6.0. (GNU-Make is the default make utility)

  • maxOS: install XCode and Xcode command line tools via command: xcode-select –install.

Function install_cmdstan

CmdStanPy provides the function install_cmdstan() which 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 $HOME directory named .cmdstan. This directory will be created by the install script.

  • From Python

import cmdstanpy
cmdstanpy.install_cmdstan()
  • From the command line on Linux or MacOSX

install_cmdstan
ls -F ~/.cmdstan
  • On Windows

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

DIY Installation

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 in the bin/ subfolder of the environment directory.

export CMDSTAN='/path/to/cmdstan-2.27.0'

The CmdStanPy commands cmdstan_path and set_cmdstan_path 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 make-tool use set_make_env function.

from cmdstanpy import set_make_env
set_make_env("mingw32-make.exe") # On Windows with mingw32-make

Footnotes

1

In very early versions, this hidden directory was named .cmdstanpy