Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
NumPyro is a probabilistic programming library for Bayesian modelling in Python. Its documentation describes it as a lightweight library that provides a NumPy backend for Pyro, and its PyPI page describes it as probabilistic programming with NumPy powered by JAX for autograd and JIT compilation to GPU, TPU or CPU. This guide is for researchers who need to install it, run a first hierarchical model with MCMC, and read the convergence diagnostics that print_summary() prints.
Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.
What NumPyro is used for in research
You write a model as a Python function in which random variables are declared with numpyro.sample, and you fit it to data with an inference algorithm. The getting-started page of the official documentation uses the NUTS sampler inside MCMC to fit the classic Eight Schools hierarchical model. Typical research uses are hierarchical (multilevel) regression, measurement-error models and any analysis where you want a full posterior distribution rather than a point estimate. If the vocabulary is new, see the CASRAI guides on Markov chain Monte Carlo and prior distributions in Bayesian statistics.
Because it runs on JAX, the same model code can run on CPU, GPU or TPU. That is the main practical difference from many other Python Bayesian tools, and it is why the installation choice below matters.
How to install or access it
As of the PyPI release page read on 2026-11-08, the current version is 0.22.0 (released 18 September 2026), it requires Python 3.11 or newer, and it is Apache-licensed. Choose the install route that matches your hardware, following the official getting-started page (read 2026-11-08).
| Target | Command or step (from the docs) |
|---|---|
| CPU (default) | pip install numpyro |
| CPU, if you hit compatibility issues | pip install 'numpyro[cpu]' forces a known compatible CPU version of JAX |
| NVIDIA GPU | Install CUDA first, then pip install 'numpyro[cuda12]' or pip install 'numpyro[cuda13]' with the JAX releases index given in the docs (-f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html) |
| TPU | Set up the TPU backend first, then pip install numpyro |
| Conda | conda install -c conda-forge numpyro |
| Development version | Clone https://github.com/pyro-ppl/numpyro.git, then pip install -e '.[dev]' inside the folder |
| Windows | The docs state NumPyro is untested on Windows and might require building jaxlib from source; they suggest Windows Subsystem for Linux instead |
The docs state that JAX uses the GPU by default when a CUDA-enabled jaxlib is installed. To force CPU, call numpyro.set_platform("cpu") at the start of your program. Record the NumPyro and JAX versions you used, and see how to cite software and packages for reporting them.
Step-by-step: fit the Eight Schools model
This is the example from the official getting-started page (read 2026-11-08). The data are eight estimated treatment effects (y) with their standard errors (sigma).
- Import the libraries and define the data.
import numpy as np import numpyro import numpyro.distributions as dist from jax import random from numpyro.infer import MCMC, NUTS J = 8 y = np.array([28.0, 8.0, -3.0, 7.0, -1.0, 1.0, 18.0, 12.0]) sigma = np.array([15.0, 10.0, 16.0, 11.0, 9.0, 11.0, 10.0, 18.0]) - Define the model. Each
numpyro.samplecall declares a random variable; passingobs=ymarks it as observed data, andnumpyro.platedeclares that the eight schools are conditionally independent.def eight_schools(J, sigma, y=None): mu = numpyro.sample('mu', dist.Normal(0, 5)) tau = numpyro.sample('tau', dist.HalfCauchy(5)) with numpyro.plate('J', J): theta = numpyro.sample('theta', dist.Normal(mu, tau)) numpyro.sample('obs', dist.Normal(theta, sigma), obs=y) - Run the NUTS sampler with 500 warm-up and 1000 sampling iterations.
nuts_kernel = NUTS(eight_schools) mcmc = MCMC(nuts_kernel, num_warmup=500, num_samples=1000) rng_key = random.key(0) mcmc.run(rng_key, J, sigma, y=y) - Print the posterior summary.
mcmc.print_summary()
The random key makes the run reproducible on the same software and hardware versions. Change the key to check that conclusions do not depend on one seed.
Output and how to read it
According to the docs, print_summary() prints one row per parameter (mu, tau and theta[0] to theta[7] here) with these columns: mean, std, median, 5.0%, 95.0%, n_eff and r_hat. The 5.0% and 95.0% columns bound a 90% posterior interval.
| Column | How to use it (per the official example) |
|---|---|
mean, std, median |
Posterior summary of each parameter |
5.0%, 95.0% |
Posterior interval limits |
n_eff |
Effective sample size; the docs treat a low value, particularly for tau, as a warning sign |
r_hat |
Split Gelman-Rubin diagnostic; the docs state that values above 1 indicate a chain has not fully converged |
The docs also report that with this model written as above (the “centered” form), sampling shows problems: r_hat above 1, low n_eff for tau, and 19 divergent transitions. They call this a common pathology and recommend a non-centered parameterization, for which they report r_hat of 1.00 for all parameters, good effective sample sizes and 0 divergences. Do not interpret the posterior of a model that shows divergences; reparameterize first, following the non-centered example in the official documentation.
Troubleshooting
- Install fails or JAX version mismatch: use
pip install 'numpyro[cpu]'to force a compatible CPU version, and confirm Python is 3.11 or newer. - GPU not used: install CUDA first, then the matching
numpyro[cuda12]ornumpyro[cuda13]extra; JAX only uses the GPU when a CUDA-enabled jaxlib is present. - You want CPU on a GPU machine: call
numpyro.set_platform("cpu")before any other NumPyro call. - Windows errors: the docs say Windows is untested; use WSL.
- Divergences, high r_hat or low n_eff: treat the fit as unreliable and reparameterize, as described above.
Free alternatives
All of these are open-source tools for Bayesian modelling; none requires a licence fee to use. Choose by the language and workflow your team already uses.
| Tool | Language / interface | Relationship to NumPyro |
|---|---|---|
| Pyro | Python, PyTorch | NumPyro is described in its docs as a NumPy backend for Pyro |
| PyMC | Python | Separate Python library for Bayesian modelling |
| Stan (e.g. via CmdStanPy) | Stan modelling language with Python, R and other interfaces | Separate system; models are written in Stan, not Python |
| brms | R | R formula interface that fits models with Stan |
For a broader view of free statistical tools by task, see free statistical software for research.
FAQ
What is NumPyro?
A probabilistic programming library built on JAX that lets you write Bayesian models in Python and fit them with MCMC (such as NUTS) or other inference algorithms. It provides a NumPy backend for Pyro.
How do I install NumPyro?
Run pip install numpyro on Python 3.11 or newer (PyPI, read 2026-11-08). For GPUs, install CUDA first and use the numpyro[cuda12] or numpyro[cuda13] extra.
Does NumPyro run on Windows?
The official docs say it is untested on Windows and might require building jaxlib from source, and suggest WSL.
What does a high r_hat mean?
Per the official example, an r_hat above 1 indicates the chain has not fully converged. Check n_eff and divergences too.
Sources
- NumPyro documentation, Getting Started: num.pyro.ai/en/stable/getting_started.html (read 2026-11-08)
- NumPyro on PyPI: pypi.org/project/numpyro (read 2026-11-08)
- NumPyro source repository: github.com/pyro-ppl/numpyro







