Pymunk is an easy-to-use pythonic 2D physics library designed for games, demos, and simulations. It is built on top of Munk2D, a fork of the robust Chipmunk2D C physics library. First released in 2007, Pymunk remains actively developed and maintained, with its current version being 7.2.0, and has a regular release cadence with several updates per year.
pip install pymunkVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates setting up a basic Pymunk simulation with a falling circle bouncing on a static ground. It covers creating a `Space`, `Body`, `Shape`, applying gravity, and stepping the simulation forward.
Migrate to `Space.on_collision()` to register callbacks for collision phases directly (e.g., `space.on_collision(collision_type_a, collision_type_b, begin=my_begin_func, pre_solve=my_pre_solve_func)`).
Unpack sequences of objects using the `*` operator (e.g., `space.add(*list_of_bodies_and_shapes)` instead of `space.add(list_of_bodies_and_shapes)`).
Ensure your project uses Python 3.6+ (preferably 3.9+ for current Pymunk versions) and update any code that mutated `Vec2d` objects, as they are now immutable. Re-assign `Vec2d` variables instead of modifying them in place.
If you need concave shapes, split them into multiple convex polygons and attach them all to the same `Body`.
To mitigate tunneling, use a smaller `dt` (time step) for `space.step()` or call `space.step()` multiple times per frame with a smaller `dt`. For very fast, small objects (like bullets), consider using `space.segment_query()` or `space.segment_query_first()` to detect intermediate collisions.
Ensure bodies have similar masses, avoid letting objects with infinite mass touch, place the center of gravity in the middle of shapes, avoid very thin shapes, and set a `max_force` on `Motor` joints to prevent infinite power.
Update collision handling code to use `space.on_collision()` instead. Refer to the Pymunk 7.0.0 changelog for migration details.
Split any concave polygon definitions into multiple convex polygons. Attach all resulting convex shapes to the same `Body`.
Reduce the `dt` (time step) passed to `space.step()`, potentially calling `space.step()` multiple times per rendering frame. For projectile-like objects, use `space.segment_query()` for accurate hit detection.
Ensure you are using `pip install pymunk` which typically provides pre-built binary wheels including Chipmunk. If installing from source, make sure Chipmunk (or Munk2D) is correctly compiled and linked. Check Pymunk's documentation for specific build requirements on your platform.