PyBullet

Common errors

• ERROR: Failed building wheel for pybullet

  cause 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.
  fix Install 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: ...

  cause 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.
  fix Ensure 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`.

Warnings

• gotcha Installing 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.
  Fix: Ensure 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).
• breaking Earlier 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.
  Fix: Upgrade PyBullet to version 3.2.5 or newer to avoid this memory leak issue. [cite: github_release_notes]
• gotcha PyBullet'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.
  Fix: To disable file caching, use `p.setPhysicsEngineParameter(enableFileCaching=0)` after connecting to the physics client.

Install

• pip install pybullet Install PyBullet

Imports

• pybullet
  wrong:

  import pybullet

  correct:

  import pybullet as p

  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'.

Quickstart

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.")