Install & Compatibility
Where this runs
tested against v3.2.7 · 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
py 3.10
✕ build_error
✓ 5.18s
py 3.11
✕ build_error
✓ 5.38s
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 8.48s
315MB installed
● package 315MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pybullet
✓ import pybullet as p
✗ import pybullet
It is conventional to import pybullet as 'p' for brevity in API calls.
pybullet_data
✓ import pybullet_data
Required to access common assets like 'plane.urdf' or 'r2d2.urdf'.
This quickstart initializes a PyBullet simulation in graphical mode, sets gravity, loads a ground plane and a simple robot model (R2D2), then runs the simulation for a short duration before disconnecting. It demonstrates the basic lifecycle of a PyBullet application.
import pybullet as p
import pybullet_data
import time
# Connect to the physics engine in GUI mode
# Use p.DIRECT for non-graphical (headless) mode
physicsClient = p.connect(p.GUI)
# Set additional search path for URDF files (e.g., plane.urdf, r2d2.urdf)
p.setAdditionalSearchPath(pybullet_data.getDataPath())
# Set gravity
p.setGravity(0, 0, -10)
# Load a plane
planeId = p.loadURDF("plane.urdf")
# Load a simple robot (e.g., R2D2)
robotStartPos = [0, 0, 1]
robotStartOrientation = p.getQuaternionFromEuler([0, 0, 0])
robotId = p.loadURDF("r2d2.urdf", robotStartPos, robotStartOrientation)
# Run the simulation for a few steps
print("Simulating...")
for i in range(1000):
p.stepSimulation()
time.sleep(1./240.) # PyBullet's default timestep is 1/240 seconds
# Disconnect from the simulator
p.disconnect()
print("Simulation finished.")
pybullet --version
Debug
Known issues
gotchaInstalling PyBullet on systems other than x64 Linux (e.g., macOS with Apple Silicon, or Windows without Visual C++ build tools) or with very recent Python versions (e.g., 3.12+) may fail due to a lack of pre-built wheels, requiring local compilation.fixEnsure C++ build tools are installed (e.g., Visual C++ Build Tools on Windows, Xcode command line tools on macOS, `build-essential` on Linux). Consider using a Python version for which wheels are readily available (e.g., 3.6-3.11 for x64 Linux).
affects: All versions, especially for non-standard environments or newer Python releases.
breakingEarlier versions (prior to 3.2.4/3.2.5) had a bug causing memory buildup when repeatedly using `createMultiBody` due to improper memory handling in some concave collision early-out reverts.fixUpgrade PyBullet to version 3.2.5 or newer to avoid this memory leak issue. [cite: github_release_notes]
affects: < 3.2.4
gotchaPyBullet's internal file caching can sometimes interfere with testing or dynamic asset loading if assets change. By default, PyBullet caches loaded files to speed up subsequent loads.fixTo disable file caching, use `p.setPhysicsEngineParameter(enableFileCaching=0)` after connecting to the physics client.
affects: All versions
Errors
Common errors & fixes
ERROR: Failed building wheel for pybullet
This error typically occurs during `pip install pybullet` when no pre-built wheel (binary distribution) is available for your specific Python version and/or operating system/architecture. This forces pip to attempt building from source, which requires a C++ compiler toolchain.
fixInstall the necessary C++ build tools for your system (e.g., `build-essential` on Linux, Xcode command line tools on macOS, Microsoft Visual C++ Build Tools on Windows). Alternatively, try installing PyBullet within a Python virtual environment that uses a Python version known to have pre-built wheels for your platform.
ImportError: .../pybullet.so: undefined symbol: ...
This `ImportError` usually happens after a manual compilation of PyBullet from source, indicating that the Python interpreter cannot find or correctly load the compiled shared library (e.g., `pybullet.so` on Linux/macOS, `_pybullet.pyd` on Windows) or its dependencies.
fixEnsure that the `PYTHONPATH` environment variable is correctly set to include the directory containing the compiled `pybullet.so` (or equivalent) file. For example: `export PYTHONPATH=/your_path_to_bullet/build_cmake/examples/pybullet:$PYTHONPATH`.
Upgrade
Version history
3.2.7latest on PyPI · released Jan 30, 2025
Audit
Dependencies
pybullet_dataoptionalProvides common URDF models and textures for simulations (e.g., planes, robots, objects).