Skip to main content
v2026.11,986 entries · CC-BY 4.0

NumPyro: Install, First Bayesian Model and Reading Output

NumPyro in JAX: install options for CPU, GPU and TPU, the official Eight Schools MCMC example, and how to read r_hat, n_eff and divergences.

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.

Ask your first question freeSubscribe

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).

  1. 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])
  2. Define the model. Each numpyro.sample call declares a random variable; passing obs=y marks it as observed data, and numpyro.plate declares 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)
  3. 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)
  4. 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] or numpyro[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

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about NumPyro: Install, First Bayesian Model and Reading Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →