PyBullet Cheat Sheet

1Install & connectGUI vs DIRECT

pip install pybullet★
Ships the Bullet engine. On Apple Silicon, if the build fails, use the pybullet-arm64 drop-in fork.
import pybullet as p cid = p.connect(p.GUI) # windowed viewer★
p.GUI opens a 3D window; p.DIRECT runs headless (no rendering — use for training/servers). Returns a physics-client id.
p.disconnect()
Tear down the server. Also SHARED_MEMORY, TCP, UDP connect modes for external servers.
# headless training? use p.DIRECT — GUI is slow and needs a displaytip
For RL rollouts run DIRECT; render only when you need to watch. Multiple sims = multiple connect() ids passed via physicsClientId=.

2World setupgravity & timestep

import pybullet_data p.setAdditionalSearchPath(pybullet_data.getDataPath())★
Add the bundled asset path so you can load stock URDFs (plane.urdf, r2d2.urdf, KUKA, etc.) by name.
p.setGravity(0, 0, -9.81) plane = p.loadURDF("plane.urdf")★
Gravity is in m/s² along Z. A ground plane is the usual first body.
p.setTimeStep(1/240) # default is 1/240 s★
The physics timestep. ⚠️ 1/240 is the tuned default — changing it affects stability; prefer more substeps over a big timestep.
p.resetSimulation() · p.setPhysicsEngineParameter(numSolverIterations=50)
Wipe the world; tune the solver (iterations, ERP, contact params) for accuracy vs speed.

3Loading bodiesURDF/SDF

robot = p.loadURDF("r2d2.urdf", basePosition=[0,0,1], baseOrientation=p.getQuaternionFromEuler([0,0,0]))★
Load an articulated body from URDF. Returns a body id you pass to every later call. Orientations are quaternions (x,y,z,w).
p.loadURDF("model.urdf", useFixedBase=True, flags=p.URDF_USE_SELF_COLLISION)
useFixedBase pins the base (e.g. a table-mounted arm). Flags toggle self-collision, inertia-from-file, etc.
p.loadSDF("world.sdf") · p.loadMJCF("model.xml")
Also loads SDF worlds and MuJoCo MJCF models (each returns a list of body ids).
p.getQuaternionFromEuler([r,p_,y]) · p.getEulerFromQuaternion(q)
Convert between Euler angles and quaternions — you'll do this constantly.

4Programmatic shapesno URDF

col = p.createCollisionShape(p.GEOM_BOX, halfExtents=[.5,.5,.5]) vis = p.createVisualShape(p.GEOM_BOX, halfExtents=[.5,.5,.5], rgbaColor=[1,0,0,1])★
Build primitives in code: GEOM_BOX, GEOM_SPHERE, GEOM_CYLINDER, GEOM_CAPSULE, GEOM_MESH.
body = p.createMultiBody(baseMass=1, baseCollisionShapeIndex=col, baseVisualShapeIndex=vis, basePosition=[0,0,2])★
createMultiBody assembles shapes into a dynamic body — the way to spawn objects without a URDF file.
p.changeDynamics(body, -1, lateralFriction=0.8, restitution=0.2)
Tune per-link physics: mass, friction, bounciness, damping. Link index -1 = the base.

5Stepping the simthe loop

for _ in range(1000): p.stepSimulation() time.sleep(1/240) # real-time pacing (GUI only)★
stepSimulation() advances one timestep. Your control & sensing go inside this loop. Sleep only for real-time viewing.
p.setRealTimeSimulation(1) # GUI auto-steps in real time
In GUI mode, let the server step itself. ⚠️ For deterministic/RL work keep it off (0) and call stepSimulation() yourself.
# nothing moves? you forgot to call stepSimulation() in a loopgotcha
Loading bodies doesn't advance physics. Time only moves when you step (or enable real-time).

6Joints & motorsactuation

n = p.getNumJoints(robot) info = p.getJointInfo(robot, i) # name, type, limits, ...★
Enumerate joints and read their metadata (index, name, type, axis, limits). You address joints by index.
p.setJointMotorControl2(robot, jointIndex, p.POSITION_CONTROL, targetPosition=1.57, force=200)★
The main actuator call. Modes: POSITION_CONTROL, VELOCITY_CONTROL, TORQUE_CONTROL. Always cap force/maxVelocity.
p.setJointMotorControlArray(robot, indices, p.POSITION_CONTROL, targetPositions=q)★
Batch-control many joints in one call — faster than a loop of ...Control2.
# TORQUE_CONTROL? first disable the default velocity motorgotcha
Loaded joints have a default velocity motor that resists your torque. Set it to VELOCITY_CONTROL, force=0 before applying torques.

7Reading stateobserve

pos, orn = p.getBasePositionAndOrientation(robot) lin, ang = p.getBaseVelocity(robot)★
Base pose (position + quaternion) & velocity in world coordinates — the core of an RL observation.
jpos, jvel, jforces, jtorque = p.getJointState(robot, i)★
Per-joint angle, velocity, reaction forces, applied torque. getJointStates(robot, indices) for a batch.
link = p.getLinkState(robot, linkIndex, computeForwardKinematics=True)
World pose/velocity of a specific link (e.g. the end-effector).
p.resetBasePositionAndOrientation(robot, pos, orn) p.resetJointState(robot, i, targetValue=0)★
Teleport state (bypassing physics) — how you reset an episode between RL rollouts.

8Kinematics & dynamicssolvers

q = p.calculateInverseKinematics(robot, eeLink, targetPos, targetOrn)★
IK: joint angles to place the end-effector at a target pose — then drive them with POSITION_CONTROL.
tau = p.calculateInverseDynamics(robot, q, qdot, qddot)
Inverse dynamics: the joint torques needed for a desired motion (feedforward control).
Jl, Ja = p.calculateJacobian(robot, link, localPos, q, qdot, qddot)
The linear & angular Jacobian at a link — for velocity/force mapping and operational-space control.
p.applyExternalForce(body, -1, forceObj=[0,0,10], posObj=[0,0,0], flags=p.WORLD_FRAME)
Inject external forces/torques (applyExternalTorque) — disturbances, thrusters, wind.

9Collision & rayscontacts

pts = p.getContactPoints(bodyA=robot, bodyB=plane) if pts: # in contact — each pt has positions, normal, force★
Contacts from the last stepSimulation. getClosestPoints(a, b, distance) for proximity without touching.
hits = p.rayTest(rayFrom, rayTo) # first-hit along a ray★
Ray casting for lidar/distance sensors. rayTestBatch shoots many rays in one call (fast lidar).
p.setCollisionFilterPair(bodyA, bodyB, linkA, linkB, enableCollision=0)
Selectively disable collisions between specific links/bodies.

10Camera & renderingsynthetic vision

view = p.computeViewMatrix(cameraEyePosition=[1,1,1], cameraTargetPosition=[0,0,0], cameraUpVector=[0,0,1]) proj = p.computeProjectionMatrixFOV(fov=60, aspect=1, nearVal=.1, farVal=10)★
Build view + projection matrices for a virtual camera.
w, h, rgb, depth, seg = p.getCameraImage(224, 224, view, proj)★
Render RGB, depth, and a segmentation mask — pixel observations for vision-based RL. Returns NumPy-able arrays.
# getCameraImage is SLOW in DIRECT without a GPU renderertip
Software (TinyRenderer) rendering is CPU-bound. Use ER_BULLET_HARDWARE_OPENGL where a GPU/display is available, and keep resolutions small.

11Debug GUIsee & tweak

s = p.addUserDebugParameter("speed", 0, 10, 1) val = p.readUserDebugParameter(s)★
Add interactive sliders/buttons to the GUI — tune parameters live without restarting.
p.addUserDebugLine(a, b, [1,0,0]) p.addUserDebugText("goal", [0,0,1])
Draw lines/text/points in the world (trajectories, forces, labels).
p.configureDebugVisualizer(p.COV_ENABLE_GUI, 0) p.resetDebugVisualizerCamera(dist, yaw, pitch, target)
Toggle GUI panels & set the viewer camera. COV_ENABLE_RENDERING, 0 to pause drawing during bulk loading (much faster).

12RL & ecosystemwhere it fits

p.saveState() · p.restoreState(stateId) · p.saveBullet("s.bullet")★
Snapshot/restore the whole world in memory or to disk — useful for planning & deterministic resets.
# RL: wrap in a Gymnasium env (reset -> obs, step(action) -> obs,r,done)★
The standard pattern: a Gym/Gymnasium Env that resets bodies, applies actions via motor control, steps, and returns observations from the state/camera calls.
# panda-gym, pybullet_robots, gym-pybullet-drones build on it
A rich ecosystem of robot models & RL benchmarks sits on PyBullet.
# newer alternatives: MuJoCo (now free), Isaac Sim/Gym, Genesis, Brax
For GPU-accelerated / photoreal sim, look at MuJoCo, Isaac, or Brax. PyBullet remains the easiest CPU-based starting point.

PyBullet cheat sheet

Outline

Connect & load

Step & control

Sensing, RL & ecosystem

Connect & Load

Step & Control

Sensing, RL & Ecosystem

Worth memorizing