REBOUND: an N-body integrator where the Python module is a thin shell over C

What the package actually integrates

REBOUND is an N-body integrator, meaning a software package that integrates the motion of particles under the influence of gravity. The particles can represent stars, planets, moons, ring or dust particles, and the project describes itself as very flexible and customizable to accurately and efficiently solve many problems in astrophysics.

That definition matters because N-body integration sounds like one thing and is several. Integrating a handful of planets on stable orbits for a billion years is a different numerical problem from following a dust particle through a close encounter with a planet, and REBOUND's design is built around that spread. It ships symplectic integrators for the long-term case, WHFast, SEI, LEAPFROG and EOS, hybrid symplectic integrators for planetary dynamics with close encounters, MERCURIUS, hybrid reversible integrators for planetary dynamics with arbitrary close encounters, TRACE, high order symplectic integrators such as SABA and the WH kernel methods, and a high accuracy non-symplectic integrator with adaptive time-stepping, IAS15.

On top of the gravity core it can integrate arbitrary user-defined ODEs that are coupled to the N-body dynamics, for tides and spin, and it supports collisional and granular dynamics with various collision detection routines.

The audience is research. The packaging metadata classifies it as Production/Stable with intended audiences of Science/Research and Developers, and the topic as Astronomy. The homepage is rebound.hanno-rein.de, and the author is Hanno Rein. The licence is GPL-3.0-only, with a LICENSE file at the root, and the last push was on 2026-10-19 with version 5.2.2 released on 2026-10-05.

The C core, the Python shell, and the absence of dependencies

The architectural decision in REBOUND is that the computationally intensive parts of the code are written entirely in C, conforming to the ISO standard C99, and can be used as a thread-safe shared library. The Python module sits on top of that library as a dynamic extension, which is why the installation is described as three words.

The setup.py makes the arrangement concrete. It exists solely to configure the dynamic C extension, with all project metadata in pyproject.toml, and it compiles with -std=c99 and -fstrict-aliasing on non-Windows platforms, along with a git hash define so the built library records the commit it came from. There is platform handling for macOS, where the shared library suffix and install_name are adjusted so the extension can find librebound at runtime, and for Windows, where clang-cl is used and a set of warning suppressions are passed.

There is also conditional AVX512 support, with the setup logic checking for a 64-bit x86 or amd64 machine, and explicitly excluding macOS and Windows without clang-cl, since the SIMD path is not portable to those.

The dependency list is empty. The project metadata declares no runtime dependencies at all, and the feature list leads with no dependencies on external libraries. The build is a plain setuptools one with setuptools>=77 and wheel, and the package data includes the C headers from src, so the shared library headers ship with the Python package.

For someone building a C program that needs gravitational dynamics, the shared library is the interface, and the examples directory has a Makefile-driven build: the top-level Makefile compiles librebound.so through src/Makefile.defs, and the echo message tells you to go into a subdirectory of examples/ and run make there to build the example problems.

Trying it in a browser, and the two-minute local install

One of the more useful features is that you can try REBOUND without installing it. The C examples have been compiled with emscripten and can run directly in your browser through the documentation site, and there is a Binder badge for the Python side.

That is a real advantage for teaching and for evaluating a piece of scientific code, because the cost of the first experiment is a page load rather than a build toolchain. The documentation site also serves as the full reference with examples, changelogs and tutorials, and there are short YouTube videos describing various aspects of REBOUND.

For local use, the Python-only install is:

pip install rebound

And the smallest useful simulation takes four lines:

import rebound
sim = rebound.Simulation()
sim.add(m=1.0)
sim.add(m=1.0e-3, a=1.0)
sim.integrate(1000.)
sim.status()

That is a two-body system, a mass of one and a mass of a thousandth at distance one, integrated for a thousand time units, with status() printing the current state. The API is built around a Simulation object you add particles to and then integrate.

The C route is the one-line clone and build of an example:

git clone https://github.com/hannorein/rebound && cd rebound/examples/shearing_sheet && make && ./rebound

The shearing sheet example is a classic test configuration for the shearing sheet dynamics that the Symplectic Epicycle integrator paper addresses, so it is a sensible first thing to run when you want to check that the C build behaves.

Performance paths, and the limits of the parallelism

REBOUND offers several ways to make the same physics faster, and the trade-offs are worth understanding because they are not interchangeable.

There is a parallelized WHFast512 integrator for very fast integrations of planetary systems using SIMD AVX512 instructions. The AVX512 path is architecture-specific, which is why the setup logic checks carefully for a 64-bit x86 or amd64 machine and bails out on arm and aarch64, and on macOS entirely.

There is parallelization with OpenMP for shared memory systems, which is the general answer for a workstation with many cores.

And there is parallelization with MPI, which is described as supported for some special use cases only, using an essential tree for gravity and collisions. That phrasing is a genuine limitation rather than a hedge. That phrasing is a genuine limitation: MPI support is not a drop-in speedup for any simulation.

What this tells you is that the performance story depends on the problem. A planetary system with well-separated orbits is the case the symplectic integrators and the SIMD path were designed for. A dense star cluster with frequent close encounters is a different regime, and the adaptive non-symplectic IAS15 is the tool the project points at for high accuracy there.

Real-time 3D visualization is available for both C and Python, and the examples directory includes directories for animations of Saturn's rings and of the solar system, which is more than a demo: it is the way to check that a simulation is doing what you expect before you trust a number from it.

Reproducibility, the companion projects, and the citation list

Reproducibility gets specific attention in REBOUND, which is appropriate for a code used to produce published results.

The paper list includes a 2017 paper on the Simulationarchive for exact reproducibility of N-body simulations, and the feature list mentions that all features are included in the public repository, with the code 100% open source. The archive mechanism is the practical part: rather than asking you to trust that your inputs and settings are enough to reconstruct a run, it records them.

The papers also document the design of each piece, so you can read the method alongside the code. The 2012 Rein and Liu paper in Astronomy and Astrophysics describes the code structure and the main features including the gravity and collision routines for many particle systems. The 2011 paper describes the Symplectic Epicycle integrator for shearing sheet simulations, the 2015 paper describes IAS15, the 2015 and 2016 papers cover WHFast and the framework for second order variational equations, the 2018 paper covers the integer based JANUS integrator, the 2019 papers cover MERCURIUS and the high order symplectic integrators SABA, SABAC, SABACL, WHCKL, WHCKM and WHCKC. The acknowledgments section asks that you cite the relevant paper if you use the code for published results.

Three related projects extend rather than replace it. REBOUNDx incorporates additional physics modules such as migration forces, GR effects and spin into REBOUND simulations. Celmech is for comparing numerical simulations to analytical and semianalytical tools for celestial mechanics. And ASSIST generates ephemeris-quality integrations of test particles in the Solar System with a precision on par with JPL's small body integrator.

That division is the main thing to check before adopting. The tidal and spin coupling REBOUND mentions in its feature list is done through user-defined ODEs, while the ready-made physics for migration forces, general relativity and spin lives in REBOUNDx, which is a separate project.

Editorial conclusion

REBOUND fits a researcher or student who needs a serious N-body integrator without a dependency stack, or a developer who wants to embed gravitational dynamics into an existing C or Python program. It is a poor fit for someone who needs the surrounding astronomy tooling, because the related projects are separate, and a poor fit if you need general relativity built in, since that comes from the companion project REBOUNDx. Before adopting, check that the integrator you need is on the list, decide between the C library and the Python module for your workload, and read the reproducibility material if your results will be published, because a Simulation archive is the mechanism the project provides for exact reruns.

Frequently asked questions

Official sources

1. hannorein/rebound on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases