pymunk wraps a forked Chipmunk core in a Python API

Python objects sitting on a forked physics core

Pymunk gives Python programmers 2D rigid body physics without asking them to think about the C library underneath. The project describes itself as an easy-to-use pythonic 2D physics library for games, demos and simulations, and it states plainly that it is built on top of Munk2D, a fork of the Chipmunk2D library.

That layering explains most of the library's character. The stated design goal is that the C library at the bottom should not be visible: no strange naming, object oriented access, no memory handling. A reader who has used Chipmunk2D directly will recognise the model, since a body, a shape, a space and a step are the same concepts, but the calling convention is Python.

The audience is a developer who already has a game loop, a visualisation layer, or a simulation harness and wants physics added without a second language. Pymunk does not force a game loop on you, and it is meant to sit next to a rendering library such as Pygame or Pyglet rather than replace one. The first version was released in 2007, the project attributes the work to Victor Blomqvist, and the release line has reached 7.3.1, with the last push on 2026-10-14.

Space, Body and Shape carry the whole model

The API surface is small and the object names carry the meaning. A Space holds the simulation. A Body carries position, velocity and mass. A Shape is attached to a body and describes its geometry, for example a box, and it is the shape that holds the mass in the example code. Objects are created independently and then added to the space together, so the space is the single registry the simulation step walks.

Simulation is explicit and driven by you. Each call to space.step advances the world by a fixed time delta, and the loop in the example runs a hundred of those steps, so nothing happens in the library unless your code asks for it. Gravity is a property of the space, set as a pair, which means each space has its own world and you can run several side by side in one process.

Rendering is deliberately left out of the core. The library offers a debug drawing facility, space.debug_draw, which in the quick example is pointed at SpaceDebugDrawOptions to print the state to the console. That is a teaching aid, not a renderer, and the actual visuals come from whatever you draw with. The step delta is yours to choose, which is also the point where the classic stability problems begin.

Installing from PyPI and stepping a first simulation

The normal case is a single pip install, and the project states that Pymunk has one direct dependency, CFFI:

pip install pymunk

There is also a conda route through the conda-forge channel:

conda install -c conda-forge pymunk

The quick example then creates a space, a body and a box shape, and steps the simulation:

import pymunk               # Import pymunk..

space = pymunk.Space()      # Create a Space which contain the simulation
space.gravity = 0,-981      # Set its gravity

body = pymunk.Body()        # Create a Body
body.position = 50,100      # Set the position of the body

poly = pymunk.Poly.create_box(body) # Create a box shape and attach to body
poly.mass = 10              # Set the mass on the shape
space.add(body, poly)       # Add both body and shape to the simulation

print_options = pymunk.SpaceDebugDrawOptions() # For easy printing

for _ in range(100):        # Run simulation 100 steps in total
    space.step(0.02)        # Step the simulation one step forward
    space.debug_draw(print_options) # Print the state of the simulation

Running that prints the state of the simulation to the console. The order of operations is worth noting for anyone coming from another engine: the shape is created against the body, the mass is set on the shape, and only then are both objects handed to the space.

CFFI and the compiled layer are not optional

Pymunk is not pure Python, and the packaging reflects that. The project lists Chipmunk, described as prebuilt and included when using binary wheels, among the requirements, alongside CFFI and setuptools. The pyproject file builds through setuptools with a CFFI build step declared in setup.py, where the cffi_modules entry points at pymunk/pymunk_extension_build.py, so building from source compiles the CFFI binding layer.

The CFFI version floor is conditional and specific. The build metadata requires cffi 1.17.1 or newer below Python 3.14, cffi 2.0.0 or newer on Python 3.14 and later for free-threaded Python support, and cffi above 1.14.0 on Emscripten. The comments in the project metadata give the reasons: versions at or below 1.14.0 have trouble returning structs from functions, and older releases cannot work with the latest setuptools.

Two details matter for anyone packaging software with Pymunk inside it. The setup script honours a PYMUNK_BUILD_SLIM environment variable, and when it is set the pymunk.examples package is left out of the distribution. There is also a release series of Pyodide wasm wheels, with 7.2.0 in November 2025 and 7.1.0 and 7.0.1 in June 2025 built around that target, so a browser deployment path exists alongside the native one.

The demos live inside the installed package

The examples are not a separate download. The project states that the demos are included in the Pymunk install, in the pymunk.examples subpackage, and that they can be run directly. Listing them is a module invocation:

python -m pymunk.examples -l

And a single demo runs the same way:

python -m pymunk.examples.index_video

The demo set is also a map of the optional dependencies. Running the Pygame based demos needs Pygame or Pygame-CE, the Pyglet based demos need Pyglet, the Matplotlib based demos need Matplotlib and Jupyter Notebook, and a few demos need Numpy. Pygame, Pyglet, Matplotlib, Jupyter Notebook and Numpy are all optional extras, listed as such in the requirements section, and the same list names GCC and friends as the optional toolchain needed to compile from source, with Visual Studio required on Windows.

That arrangement has a practical effect. The examples are the fastest way to see the library do something visual, and the fact that they live in the pymunk.examples package means they are also the reason the slim build flag exists. A distribution that only needs the physics can drop the examples and their drawing dependencies entirely.

The Python version floor moves with every major release

The compatibility policy is explicit and the pattern is consistent. Support for Python 2, and for Python 3.0 through 3.5, was dropped with Pymunk 6.0. Support for Python 3.6 was dropped in 6.5.2, for 3.7 in 6.9.0, and for 3.8 in 7.0.0. The current metadata classifies the project for Python 3.9 and later, and the requirements section says it runs on CPython 3.9 and later as well as PyPy3.

The guidance for anyone still on an old interpreter is blunt: use an older Pymunk version. The project adds that an older version might work on a newer Pymunk but is not tested, and no wheels are built for those legacy versions. That last clause is the one that bites. Without a wheel you are compiling from source, which means a working compiler toolchain on the target machine, and Visual Studio on Windows.

Pymunk is MIT licensed, with the licence text in LICENSE.txt, and the metadata records the licence file alongside the project. The repository also carries a CITATION.cff file, a CHANGELOG.rst, a THANKS.txt and a TODO.txt, which together suggest a project with an orderly release record even though the work is carried largely by one author. The last push was on 2026-10-14 and the package version in the metadata is 7.3.1.

Where Chipmunk2D directly would fit better

The alternative is not a different physics idea but a different binding choice, and the difference shows up in three places. Writing against Chipmunk2D directly means you work with the C library, its own naming, its own memory rules, and its own build step, and you are responsible for keeping the Python and C sides in step. Pymunk exists to remove exactly that, and it says so in its stated vision: no complicated code should be needed to add physics, and the C library at the bottom should not be visible.

The second difference is how much of the surrounding program you own. Pymunk is non-intrusive by design: it does not put restrictions on how you structure your program and does not force a special game loop, so it composes with a rendering library such as Pygame or Pyglet. A direct C integration tends to pull the whole loop into the physics library's shape. The third difference is distribution. Pymunk publishes wheels and works on Windows, *nix and OSX, which for a Python application means the end user runs pip install and nothing else.

The trade runs the other way when you want the fork's changes and nothing else. Pymunk is built on Munk2D, a fork of Chipmunk2D, and it pins a specific Munk2D revision, so the library you get is a particular lineage rather than the upstream project. Anyone who needs to stay on the original Chipmunk2D codebase, or who already has a working C binding, gains little from the wrapper.

Editorial conclusion

pymunk is the right fit for 2D rigid body work in Python where you want readable object code and a stepping loop you control, including scientific or agent simulations that have nothing to do with games. It is the wrong fit if a pure Python install with no compiled extension matters more than the API, or if you need 3D. Verify first that a wheel exists for your interpreter and platform, since the project drops old Python versions on a schedule and builds no wheels for them, and that your CFFI version clears the floor the build requires for your Python release.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. viblo/pymunk on GitHub