Registry / ai-ml / pymunk

pymunk

JSON →
library7.2.0pypypi✓ verified 87d ago

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 pymunk
INSTALL
IMPORT
SIG · PYMUNK
P
pymunk
ai-mlpythonv7.2.0
Install
2.1s avg
Import
59ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v7.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.062s · 22.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.1s · import 0.056s · 24MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pymunk
import pymunk
Space
from pymunk import Space
Central class for the physics simulation world.
Body
from pymunk import Body
Represents a rigid body in the simulation.
Shape (e.g., Circle, Poly, Segment)
from pymunk.shapes import Circle, Poly, Segment
Collision shapes attached to bodies.
Vec2d
from pymunk import Vec2d
some_vector_var = [x, y]
Vec2d was overhauled in 6.0.0 to be an immutable NamedTuple. While lists/tuples might sometimes work implicitly, explicit Vec2d or tuple usage is preferred and type-hint friendly.

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.

import pymunk # 1. Create a Space (the simulation world) space = pymunk.Space() space.gravity = 0, -981 # Set gravity (e.g., 9.81 m/s^2 downwards) # 2. Create a Body (the physical object) mass = 1 moment = pymunk.moment_for_circle(mass, 0, 10) # Moment of inertia for a circle body = pymunk.Body(mass, moment) body.position = 50, 150 # Initial position of the body # 3. Create a Shape (for collision detection) and attach to the Body circle_shape = pymunk.Circle(body, 10) # 10 is radius circle_shape.friction = 0.7 circle_shape.elasticity = 0.9 # 4. Create a static ground for the ball to land on ground_shape = pymunk.Segment(space.static_body, (0, 0), (200, 0), 5) # From (0,0) to (200,0) with radius 5 ground_shape.friction = 0.7 ground_shape.elasticity = 0.9 ground_shape.color = (0, 0, 0, 255) # 5. Add the Body and Shape to the Space space.add(body, circle_shape, ground_shape) # 6. Simulate the physics print(f"Initial position: {body.position}") for i in range(100): # Run 100 steps of the simulation space.step(1 / 60.0) # Advance the simulation by 1/60th of a second if i % 10 == 0: print(f"Step {i}: Position: {body.position}") print(f"Final position: {body.position}")
Debug
Known issues
breakingPymunk 7.0.0 introduced significant breaking changes to collision handling. The `Space.add_collision_handler()` method and the `CollisionHandler` object were removed.
fix
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)`).
affects: 7.0.0+
breakingIn Pymunk 7.0.0, methods like `Space.add()` and `Space.remove()` no longer accept lists or tuples of objects.
fix
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)`).
affects: 7.0.0+
breakingPymunk 6.0.0 dropped support for Python 2.x and required Python 3.6 or newer. Additionally, the `Vec2d` vector class was completely overhauled to be an immutable `NamedTuple` subclass with a streamlined API.
fix
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.
affects: 6.0.0+
gotchaPymunk's underlying Chipmunk library does not directly support concave polygons for collision detection due to performance and complexity. When a concave polygon is provided, Pymunk will attempt to create a convex hull, potentially resulting in an unexpected shape.
fix
If you need concave shapes, split them into multiple convex polygons and attach them all to the same `Body`.
affects: All versions
gotchaFast-moving objects can 'tunnel' through other objects if they move too quickly during a single physics step (`space.step()`), causing collisions to be missed.
fix
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.
affects: All versions
gotchaUnstable simulations (e.g., objects 'blowing up' or moving illogically) can occur with certain physics configurations.
fix
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.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'Space' object has no attribute 'add_collision_handler'
Attempting to use the `add_collision_handler` method, which was removed in Pymunk 7.0.0.
fix
Update collision handling code to use `space.on_collision()` instead. Refer to the Pymunk 7.0.0 changelog for migration details.
Pymunk polygon vertices not correct / Polygon appears as a square instead of the intended shape
Attempting to create a `Poly` shape with concave vertices. Pymunk automatically creates a convex hull, simplifying the shape.
fix
Split any concave polygon definitions into multiple convex polygons. Attach all resulting convex shapes to the same `Body`.
Objects pass through each other without colliding (object tunneling)
Objects are moving too fast, causing them to completely traverse other objects between discrete physics steps.
fix
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.
AttributeError: /usr/lib/python3.x/site-packages/pymunk/libchipmunk64.so: undefined symbol: cpInitChipmunk (or similar linking errors)
This error, common in older versions or when installing from source, indicates a problem with Pymunk finding or linking to the underlying Chipmunk C library.
fix
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.
Upgrade
Version history
7.2.0latest on PyPI · released Nov 2, 2025
Audit
Dependencies
cffirequiredDirect dependency required for Python-C integration with Munk2D.
Agent activity
12 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources
pymunk — pip install pymunk · libregistry