!PyVBMC

PyVBMC: Variational Bayesian Monte Carlo in Python

PyVBMC is one of the open-source tools for fitting models to data from the Machine and Human Intelligence Group at the University of Helsinki. Check out our other tools, such as PyBADS for point estimates and PyIBS for models that can only be simulated.

What is it?

PyVBMC [1] is a Python implementation of the Variational Bayesian Monte Carlo (VBMC) algorithm for posterior and model inference, previously implemented in MATLAB. VBMC is an approximate inference method designed to fit and evaluate Bayesian models with a limited budget of potentially noisy likelihood evaluations (e.g., for computationally expensive models). Specifically, VBMC simultaneously computes:

• an approximate posterior distribution of the model parameters;
• an approximation — technically, an approximate lower bound — of the log model evidence (also known as log marginal likelihood), a metric used for Bayesian model selection.

Watch a three-minute film that explains how PyVBMC works.

What's new in PyVBMC 1.5

The main additions and changes in PyVBMC 1.5 are:

• Faster, slightly more accurate inference and lower memory use, with numerical improvements and more compact run histories: on our benchmark suite a run takes on average 3.7 times less time than with PyVBMC 1.0.4 on noiseless targets and 2.2 times less on noisy ones, and the typical error of the estimates of the model evidence and of the posterior is about 10% smaller. Optional performance calibration tunes PyVBMC for your machine.
• Corrections and safeguards, with corrections to the algorithm, most of them from a systematic comparison with the original MATLAB VBMC; a check that keeps the final boost from replacing a good posterior with a much worse one; and clear errors for option values that earlier versions ignored or misread.
• Stacking Variational Bayesian Monte Carlo (S-VBMC) is included in PyVBMC to combine posteriors from independent runs (Silvestrin et al., 2025; usage below).
• Explicit random seed control for reproducing individual runs; see the reproducibility guide.
• Torch and JAX model integration through small user-written wrappers, with optional batch evaluation of the initial points; see the model integration guide.
• Direct PyMC model support, with automatic setup and posterior samples exported under the model's variable names; see the PyMC integration guide.
• Posterior exports to Torch and ArviZ for further analysis; see the export guide.
• More practical guidance, with tips when a run starts, a PyVBMC FAQ, and a coding-agent skill that points agents to the relevant documentation.

Documentation

The full documentation is available at: https://acerbilab.org/pyvbmc/

Its FAQ collects questions and answers on installing PyVBMC, setting up the target, the prior and the bounds, noisy targets, reading the results, and runs that go wrong.

For coding agents, the PyVBMC skill points to the documentation relevant to each task. Give your agent that file, or copy the skills/pyvbmc folder into its skill directory. To update a copied skill, copy the folder again from the PyVBMC version you use.

When should I use PyVBMC?

PyVBMC is effective when:

• the model log-likelihood function is a black-box (e.g., the gradient is unavailable);
• likelihood evaluations are moderately expensive (say, around 0.1 seconds or more) or noisy;
• the model has up to D = 10 continuous parameters (maybe a few more, but no more than D = 20);
• the target posterior distribution is continuous and reasonably smooth (see here).

For a fast, noiseless likelihood, consider inference methods such as MCMC, available in probabilistic programming frameworks such as Stan or PyMC; PyMC users with an expensive supported model can pass it to PyVBMC through PyMCTarget.

Note: Our model-fitting tools include Bayesian Adaptive Direct Search in Python (PyBADS) for finding point estimates or better starting points for PyVBMC.

Installation

PyVBMC is available via pip and conda-forge.

1. Install or upgrade with pip:

python -m pip install --upgrade pyvbmc

conda install --channel=conda-forge pyvbmc

PyVBMC 1.5 requires NumPy 2.0, SciPy 1.15 and matplotlib 3.9 or newer, and its conda-forge package requires Python 3.11 or newer. In an environment that holds an older version of one of them, conda can install PyVBMC 1.0.4 instead, without a warning: ask it for "pyvbmc>=1.5", or see the FAQ.

1. (Optional): Install Jupyter Notebook to run the examples. You can skip this step if your environment already has Jupyter Notebook, but be aware that if the wrong jupyter executable is found on your path then import errors may arise.

python -m pip install notebook

conda install --channel=conda-forge jupyter

python -m pyvbmc

Optional integrations are installed separately. S-VBMC and the Torch posterior export (see below) use the torch extra. For a CPU-only torch setup, install the official CPU wheel first, followed by the PyVBMC extra:

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install --upgrade "pyvbmc[torch]"

python -m pip install --upgrade "pyvbmc[arviz]"

python -m pip install --upgrade "pyvbmc[pymc]"

If you wish to install directly from latest source code, please see the instructions for developers and contributors.

Optional performance calibration

Optionally, we recommend running calibration once to tune performance for your machine (memory, processor, etc.):

from pyvbmc import calibrate
calibrate()

Run this when your machine is otherwise idle. It takes tens of seconds and can make PyVBMC run faster. The settings are saved and reused automatically by future runs with a compatible numerical environment. See the calibration guide for details.

Quick start

1. Define the model, which defines a target log density (i.e., an unnormalized log posterior density);
2. Set up the parameters (parameter bounds, starting point);
3. Initialize and run the inference;
4. Examine and visualize the results.

from pyvbmc import VBMC
... define your model/target density here
vbmc = VBMC(target, x0, LB, UB, PLB, PUB)
vp, results = vbmc.optimize()

• target: the target (unnormalized) log density — often an unnormalized log posterior. target is a callable that should take as input a parameter vector and return the log density at the point. The returned log density must be a finite real value, i.e. neither NaN nor +/-inf. See the PyVBMC FAQ for more details;
• x0: an array representing the starting point of the inference in parameter space;
• LB and UB: arrays of hard lower (resp. upper) bounds constraining the parameters (possibly -/+np.inf for unbounded parameters);
• PLB and PUB: arrays of plausible lower (resp. upper) bounds: that is, a box that ideally brackets a high posterior density region of the target.

The outputs are:

• vp: a VariationalPosterior object which approximates the true target density;
• results: a dict containing additional information. Important keys are:

The vp object can be manipulated in various ways. For example, we can draw samples from vp with the vp.sample() method, or evaluate its density at a point with vp.pdf() (or log-density with vp.log_pdf()). See the VariationalPosterior class documentation for details.

PyVBMC with noisy targets

The quick start example above works for deterministic (noiseless) evaluations of the target log-density. PyVBMC also supports noisy evaluations of the target. Noisy evaluations often arise from simulation-based models, for which a direct expression of the (log) likelihood is not available.

For information on how to run PyVBMC on a noisy target, see this example notebook and the PyVBMC FAQ.

Note that VBMC(seed=...) only controls the internal random stream of PyVBMC and not that of your simulations. Reproducing the analysis also requires setting the simulator's seed before the run. See the reproducibility guide for how to do this.

Combine runs and use the posterior downstream

Combine runs: Stacking Variational Bayesian Monte Carlo (S-VBMC; Silvestrin et al., 2025) is a technique to combine the posteriors of several completed PyVBMC runs on the same model and data into a stacked posterior. Stacking the posteriors almost always provides a better approximation of the true posterior (sometimes much better), and it works as a post-processing step that does not require further model evaluations. See Example 7 and the SVBMC documentation.

Export posteriors: A fitted VariationalPosterior can also be exported as a Torch distribution with vp.to_torch(), or as samples in an ArviZ DataTree with vp.to_arviz(). See the posterior export guide and PyVBMC Example 9: Torch and JAX models and posterior exports for worked examples, including posterior predictions and density gradients in Torch and summaries in ArviZ.

Next steps

Once installed, example Jupyter notebooks can be found in the pyvbmc/examples directory. They can also be viewed statically on the main documentation pages. These examples will walk you through the basic usage of PyVBMC as well as some of its more advanced features.

For practical recommendations, such as how to set LB and UB and the plausible bounds, check out the PyVBMC FAQ.

How does it work?

Watch a three-minute film that explains how PyVBMC works.

VBMC/PyVBMC combine two machine learning techniques in a novel way:

• variational inference, a method to perform approximate Bayesian inference;
• Bayesian quadrature, a technique to estimate the value of expensive integrals.

This matching process entails optimization of the evidence lower bound (ELBO), that is a lower bound on the log marginal likelihood (LML), also known as log model evidence. Crucially, we estimate the ELBO via Bayesian quadrature, which is fast and does not require further evaluation of the true target posterior.

In each iteration, PyVBMC uses active sampling to select which points to evaluate next in order to explore the posterior landscape and reduce uncertainty in the approximation.

!VBMC Demo

In the figure above, we show an example PyVBMC run on a Rosenbrock "banana" function. The bottom-left panel shows PyVBMC at work: in grayscale are samples from the variational posterior (drawn as small points) and the corresponding estimated density (drawn as contours). The solid orange circles are the active sampling points chosen at each iteration, and the hollow blue circles are the previously sampled points. The topmost and rightmost panels show histograms of the marginal densities along the $x_1$ and $x_2$ dimensions, respectively. PyVBMC converges to an excellent approximation of the true posterior with a few dozen evaluations of the target density.

See the VBMC papers [1-3] for more details.

Troubleshooting and contact

PyVBMC is under active development. The VBMC algorithm has been extensively tested in several benchmarks and published papers, and the benchmarks have been replicated using PyVBMC. But as with any approximate inference technique, you should double-check your results. See the examples for descriptions of the convergence diagnostics and suggestions on validating PyVBMC's results with multiple runs.

Many questions are answered in the FAQ. Its Troubleshooting section says how to check that a run went well, and covers runs that have not converged, targets that return invalid values, results that differ from run to run, and saving, continuing and combining runs.

If the FAQ does not help, you spot bugs or strange behavior, or you simply have some questions, please feel free to:

• Post in the lab's Discussions forum with questions or comments about PyVBMC, your problems & applications;
• Open an issue on GitHub;
• Contact the project lead at , putting 'PyVBMC' in the subject of the email.

References and citation

1. Huggins, B., Li, C., Tobaben, M., Aarnos, M., & Acerbi, L. (2023). PyVBMC: Efficient Bayesian inference in Python. Journal of Open Source Software 8(86), 5428, https://doi.org/10.21105/joss.05428.
2. Acerbi, L. (2018). Variational Bayesian Monte Carlo. In Advances in Neural Information Processing Systems 31: 8222-8232. (paper + supplement on arXiv, NeurIPS Proceedings)
3. Acerbi, L. (2020). Variational Bayesian Monte Carlo with Noisy Likelihoods. In Advances in Neural Information Processing Systems 33: 8211-8222 (paper + supplement on arXiv, NeurIPS Proceedings).

We estimated approximate posterior distributions and approximate lower bounds to the model evidence of our models using Variational Bayesian Monte Carlo (VBMC; Acerbi, 2018, 2020) via the PyVBMC software (Huggins et al., 2023). PyVBMC combines variational inference and active-sampling Bayesian quadrature to perform approximate Bayesian inference in a sample-efficient manner.

If you use S-VBMC (see Additional references), please also add a sentence such as:

We combined posteriors from independent PyVBMC runs on the same model and dataset using S-VBMC (Silvestrin et al., 2025).

Besides formal citations, you can demonstrate your appreciation for PyVBMC in the following ways:

• Star :star: the PyVBMC repository on GitHub;
• Follow Luigi Acerbi on X or Bluesky for updates about VBMC/PyVBMC and other projects;
• Tell us about your model-fitting problem and your experience with PyVBMC (positive or negative) in the lab's Discussions forum.

Additional references

1. Acerbi, L. (2019). An Exploration of Acquisition and Mean Functions in Variational Bayesian Monte Carlo. In Proc. Machine Learning Research 96: 1-10. 1st Symposium on Advances in Approximate Bayesian Inference, Montréal, Canada. (paper in PMLR)

1. Silvestrin, F., Li, C., & Acerbi, L. (2025). Stacking Variational Bayesian Monte Carlo. Transactions on Machine Learning Research. (paper + supplement on arXiv, TMLR)

BibTeX

@article{huggins2023pyvbmc,
    title = {PyVBMC: Efficient Bayesian inference in Python},
    author = {Bobby Huggins and Chengkun Li and Marlon Tobaben and Mikko J. Aarnos and Luigi Acerbi},
    publisher = {The Open Journal},
    journal = {Journal of Open Source Software},
    url = {https://doi.org/10.21105/joss.05428},
    doi = {10.21105/joss.05428},
    year = {2023},
    volume = {8},
    number = {86},
    pages = {5428}
  }
@article{acerbi2018variational,
  title={{V}ariational {B}ayesian {M}onte {C}arlo},
  author={Acerbi, Luigi},
  journal={Advances in Neural Information Processing Systems},
  volume={31},
  pages={8222--8232},
  year={2018}
}
@article{acerbi2020variational,
  title={{V}ariational {B}ayesian {M}onte {C}arlo with noisy likelihoods},
  author={Acerbi, Luigi},
  journal={Advances in Neural Information Processing Systems},
  volume={33},
  pages={8211--8222},
  year={2020}
}
@article{silvestrin2025stacking,
  title={Stacking {V}ariational {B}ayesian {M}onte {C}arlo},
  author={Silvestrin, Francesco and Li, Chengkun and Acerbi, Luigi},
  journal={Transactions on Machine Learning Research},
  year={2025},
  url={https://openreview.net/forum?id=M2ilYAJdPe}
}
@article{acerbi2019exploration,
  title={An Exploration of Acquisition and Mean Functions in {V}ariational {B}ayesian {M}onte {C}arlo},
  author={Acerbi, Luigi},
  journal={PMLR},
  volume={96},
  pages={1--10},
  year={2019}
}

License

PyVBMC is released under the terms of the BSD 3-Clause License.

Acknowledgments

PyVBMC is developed by members (past and current) of the Machine and Human Intelligence Group at the University of Helsinki and ELLIS Institute Finland. Development of PyVBMC 1.5 was assisted by coding agents, including Anthropic's Claude Fable 5.1 and OpenAI's GPT-6 Astra. Work on the PyVBMC package is supported by the Research Council of Finland (grants 356498 and 358980 to Luigi Acerbi) and its Flagship programme: Finnish Center for Artificial Intelligence FCAI.