{"id":5422,"library":"pystan","title":"PyStan","description":"PyStan is a Python interface to Stan, a powerful platform for Bayesian inference and high-performance statistical computation. It allows users to define statistical models using Stan's probabilistic programming language and fit them using Hamiltonian Monte Carlo (HMC) methods. Currently at version 3.10.1, PyStan focuses on providing a reliable HMC sampler, with a development cadence that sees frequent updates to minor versions.","status":"active","version":"3.10.1","language":"en","source_language":"en","source_url":"https://github.com/stan-dev/pystan","tags":["Bayesian inference","MCMC","statistics","sampling","Hamiltonian Monte Carlo","probabilistic programming"],"install":[{"cmd":"pip install pystan","lang":"bash","label":"PyPI (requires C++ compiler)"},{"cmd":"conda install pystan -c conda-forge","lang":"bash","label":"Conda-forge (may include compiler)"}],"dependencies":[{"reason":"Required for compiling Stan models during installation and runtime. Often needs to be installed separately from Python.","package":"C++ compiler (e.g., gcc >=9.0 or clang >=10.0)","optional":false},{"reason":"Fundamental for numerical operations and data handling.","package":"NumPy","optional":false},{"reason":"Used for generating C extensions for performance.","package":"Cython","optional":false},{"reason":"Optional, but recommended for convenient data manipulation and extracting fit results into DataFrames using `to_frame()`.","package":"pandas","optional":true},{"reason":"Recommended for post-sampling analysis, diagnostics, and plotting, as some summary/diagnostic functions (e.g., `stansummary`, `check_hmc_diagnostics`) were removed from PyStan 3.","package":"arviz","optional":true},{"reason":"Required for running PyStan 3 within environments like Jupyter notebooks that use asyncio event loops.","package":"nest-asyncio","optional":true}],"imports":[{"note":"PyStan 3 uses 'import stan' instead of 'import pystan' (used in v2.x) to align with other Stan interfaces.","wrong":"import pystan","symbol":"stan","correct":"import stan"}],"quickstart":{"code":"import stan\nimport numpy as np\n\nschools_code = \"\"\"\ndata {\n  int<lower=0> J; // number of schools\n  array[J] real y; // estimated treatment effects\n  array[J] real<lower=0> sigma; // standard error of effect estimates\n}\nparameters {\n  real mu; // population treatment effect\n  real<lower=0> tau; // standard deviation in treatment effects\n  vector[J] eta; // unscaled deviation from mu by school\n}\ntransformed parameters {\n  vector[J] theta = mu + tau * eta; // school treatment effects\n}\nmodel {\n  target += normal_lpdf(eta | 0, 1); // prior log-density\n  target += normal_lpdf(y | theta, sigma); // log-likelihood\n}\n\"\"\"\n\nschools_data = {\n    \"J\": 8,\n    \"y\": [28, 8, -3, 7, -1, 1, 18, 12],\n    \"sigma\": [15, 10, 16, 11, 9, 11, 10, 18],\n}\n\n# Build the model (compiles Stan code to C++ and then to executable)\nposterior = stan.build(schools_code, data=schools_data, random_seed=1)\n\n# Sample from the posterior distribution\nfit = posterior.sample(num_chains=4, num_samples=1000)\n\n# Extract samples for a parameter\nmu_samples = fit[\"mu\"]\nprint(f\"Mean of mu samples: {np.mean(mu_samples)}\")\n\n# To get a pandas DataFrame (requires pandas installed):\n# import pandas as pd\n# df = fit.to_frame()\n# print(df.head())","lang":"python","description":"This quickstart demonstrates how to define a Stan model, provide data, build the model, sample from the posterior distribution using HMC, and extract results for analysis. It uses the classic 'Eight Schools' hierarchical model. The `stan.build()` step compiles the model, which can take some time. `posterior.sample()` then runs the MCMC chains."},"warnings":[{"fix":"Consult the 'Upgrading to Newer Releases' section in the official documentation. Update import statements (`import stan`), function calls (`build`, `sample`), and parameter names (`num_samples`).","message":"PyStan 3 is a complete rewrite and introduces numerous backwards-incompatible changes from PyStan 2.x. Key API changes include `pystan.StanModel()` becoming `stan.build()`, `fit.sampling()` becoming `fit.sample()`, and `iter` parameter changing to `num_samples`.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Install and configure WSL2, then install PyStan within the Linux environment. Alternatively, use CmdStanPy or another Stan interface that supports Windows directly.","message":"Microsoft Windows is no longer officially supported for PyStan 3.x installations. Users on Windows are advised to use Windows Subsystem for Linux 2 (WSL2) to run PyStan, or consider alternative Stan interfaces like CmdStanPy.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Ensure that your data dictionary and `random_seed` argument are passed to `stan.build()` when initializing your model, e.g., `posterior = stan.build(model_code, data=my_data, random_seed=123)`.","message":"In PyStan 3.x, data and `random_seed` must be passed during the `stan.build()` step (compile time), not during the `fit.sample()` step (sampling time), unlike PyStan 2.x.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"For these features, consider using alternative Stan interfaces (like CmdStanPy or RStan) or other probabilistic programming libraries (e.g., PyMC, JAX, PyTorch for VI/maximization). For diagnostics, use the ArviZ library.","message":"PyStan 3.x significantly reduces its scope. Variational inference, maximization algorithms (e.g., LBFGS), and samplers other than the default HMC sampler are no longer supported. The `stansummary` display and `check_hmc_diagnostics` functions have also been removed.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Ensure you have a compatible C++ compiler installed (e.g., gcc >=9.0 or clang >=10.0 on Linux/macOS). On Debian-based systems, `apt-get install build-essential` often suffices. For Windows, WSL2 is the recommended approach.","message":"PyStan requires a C++ compiler to be available both during installation and at runtime for compiling Stan models. Lack of a properly configured compiler is a common cause of installation and runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install and use `nest-asyncio` by adding `import nest_asyncio; nest_asyncio.apply()` at the beginning of your notebook or script to allow nested event loops.","message":"When running PyStan 3.x in Jupyter notebooks or other environments that manage their own `asyncio` event loops, `RuntimeError: asyncio.run() cannot be called from a running event loop` may occur.","severity":"gotcha","affected_versions":"3.0.0 and later"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}