{"id":7590,"library":"pymunk","title":"Pymunk","description":"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.","status":"active","version":"7.2.0","language":"en","source_language":"en","source_url":"https://github.com/viblo/pymunk.git","tags":["physics","2d","game-development","simulation","chipmunk","munk2d"],"install":[{"cmd":"pip install pymunk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Direct dependency required for Python-C integration with Munk2D.","package":"cffi","optional":false}],"imports":[{"symbol":"pymunk","correct":"import pymunk"},{"note":"Central class for the physics simulation world.","symbol":"Space","correct":"from pymunk import Space"},{"note":"Represents a rigid body in the simulation.","symbol":"Body","correct":"from pymunk import Body"},{"note":"Collision shapes attached to bodies.","symbol":"Shape (e.g., Circle, Poly, Segment)","correct":"from pymunk.shapes import Circle, Poly, Segment"},{"note":"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.","wrong":"some_vector_var = [x, y]","symbol":"Vec2d","correct":"from pymunk import Vec2d"}],"quickstart":{"code":"import pymunk\n\n# 1. Create a Space (the simulation world)\nspace = pymunk.Space()\nspace.gravity = 0, -981  # Set gravity (e.g., 9.81 m/s^2 downwards)\n\n# 2. Create a Body (the physical object)\nmass = 1\nmoment = pymunk.moment_for_circle(mass, 0, 10) # Moment of inertia for a circle\nbody = pymunk.Body(mass, moment)\nbody.position = 50, 150 # Initial position of the body\n\n# 3. Create a Shape (for collision detection) and attach to the Body\ncircle_shape = pymunk.Circle(body, 10) # 10 is radius\ncircle_shape.friction = 0.7\ncircle_shape.elasticity = 0.9\n\n# 4. Create a static ground for the ball to land on\nground_shape = pymunk.Segment(space.static_body, (0, 0), (200, 0), 5) # From (0,0) to (200,0) with radius 5\nground_shape.friction = 0.7\nground_shape.elasticity = 0.9\nground_shape.color = (0, 0, 0, 255)\n\n# 5. Add the Body and Shape to the Space\nspace.add(body, circle_shape, ground_shape)\n\n# 6. Simulate the physics\nprint(f\"Initial position: {body.position}\")\nfor i in range(100): # Run 100 steps of the simulation\n    space.step(1 / 60.0) # Advance the simulation by 1/60th of a second\n    if i % 10 == 0:\n        print(f\"Step {i}: Position: {body.position}\")\n\nprint(f\"Final position: {body.position}\")","lang":"python","description":"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."},"warnings":[{"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)`).","message":"Pymunk 7.0.0 introduced significant breaking changes to collision handling. The `Space.add_collision_handler()` method and the `CollisionHandler` object were removed.","severity":"breaking","affected_versions":"7.0.0+"},{"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)`).","message":"In Pymunk 7.0.0, methods like `Space.add()` and `Space.remove()` no longer accept lists or tuples of objects.","severity":"breaking","affected_versions":"7.0.0+"},{"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.","message":"Pymunk 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.","severity":"breaking","affected_versions":"6.0.0+"},{"fix":"If you need concave shapes, split them into multiple convex polygons and attach them all to the same `Body`.","message":"Pymunk'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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Fast-moving objects can 'tunnel' through other objects if they move too quickly during a single physics step (`space.step()`), causing collisions to be missed.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Unstable simulations (e.g., objects 'blowing up' or moving illogically) can occur with certain physics configurations.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update collision handling code to use `space.on_collision()` instead. Refer to the Pymunk 7.0.0 changelog for migration details.","cause":"Attempting to use the `add_collision_handler` method, which was removed in Pymunk 7.0.0.","error":"AttributeError: 'Space' object has no attribute 'add_collision_handler'"},{"fix":"Split any concave polygon definitions into multiple convex polygons. Attach all resulting convex shapes to the same `Body`.","cause":"Attempting to create a `Poly` shape with concave vertices. Pymunk automatically creates a convex hull, simplifying the shape.","error":"Pymunk polygon vertices not correct / Polygon appears as a square instead of the intended shape"},{"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.","cause":"Objects are moving too fast, causing them to completely traverse other objects between discrete physics steps.","error":"Objects pass through each other without colliding (object tunneling)"},{"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.","cause":"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.","error":"AttributeError: /usr/lib/python3.x/site-packages/pymunk/libchipmunk64.so: undefined symbol: cpInitChipmunk (or similar linking errors)"}]}