CmdStanPy is the official Python interface to CmdStan, a command-line program for fitting statistical models written in Stan. It facilitates compiling Stan models, running MCMC, optimization, and variational inference, and processing the results. Currently at version 1.3.0, it follows a regular release cadence with minor updates every few months, and a major 2.0 release planned to remove existing deprecations.
pip install cmdstanpyVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define, compile, and fit a simple Bernoulli model using CmdStanPy. It includes essential steps to ensure the underlying CmdStan C++ program is available, either by setting its path or by automatically installing it. The example compiles a Stan file, provides data, runs MCMC sampling, and prints a summary of the results.
Consult CmdStanPy documentation for current deprecations (e.g., replace `output_basename` with `output_dir`) and update code accordingly.
Before using CmdStanPy, either run `cmdstanpy.install_cmdstan()` once, or install CmdStan manually and set the `CMDSTAN_PATH` environment variable or call `cmdstanpy.set_cmdstan_path()`.
Replace `output_basename='my_output'` with `output_dir='path/to/output'` (which defaults to a temporary directory if not specified).
Upgrade CmdStanPy to version 1.2.4 or newer to ensure compatibility with CmdStan 2.35 and later versions.
Ensure `make` is installed in your environment. For Alpine Linux (like `python:3.13-alpine`), this can typically be done with `apk add make`. For other distributions, use their respective package managers (e.g., `apt-get install make` on Debian/Ubuntu, `yum install make` on CentOS/RHEL).
Ensure a compatible C++ toolchain is installed (e.g., Xcode command line tools on macOS, RTools 4.0 with g++ 8 on Windows, or `g++` on Linux). If issues persist, try rebuilding CmdStan using `cmdstanpy.rebuild_cmdstan()` to address potential PCH file corruption. Verify that the necessary environment variables for your toolchain are correctly set.
To resolve this, install CmdStan by running `cmdstanpy.install_cmdstan()` in Python. If installed via conda, ensure your environment is activated (`conda activate your_env_name`). If CmdStan is installed in a non-default location, explicitly set the `CMDSTAN` environment variable (e.g., `os.environ['CMDSTAN'] = '/path/to/cmdstan'`).
First, re-run the sampling with `show_console=True` in the `model.sample()` call to view direct CmdStan output. Check model diagnostics (`fit.diagnose()` after a successful run, if possible). Review model initializations and consider adjusting sampler parameters like `adapt_delta` or `max_treedepth`. Ensure sufficient system resources (RAM) are available.
Ensure your Python environment is running a version compatible with CmdStanPy's requirements (typically Python 3.8 or newer for features like the walrus operator). It is recommended to create a fresh virtual environment with an appropriate Python version and reinstall `cmdstanpy` and its dependencies there.