Simulation lets you run a full openpilot stack — controls, planning, and perception — without a physical car or comma device. openpilot uses the MetaDrive simulator via a bridge process that translates between openpilot’s internal message bus and the simulator’s API. This is useful for validating control logic changes, testing new features, and iterating quickly without any road time.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/commaai/openpilot/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
The simulator requires thetools optional dependencies, which include the MetaDrive package. Install them into your virtual environment:
MetaDrive is only available on x86_64 (AMD64) machines. It is not supported on ARM (aarch64), including Apple Silicon Macs running Linux in a VM.
Running the simulation
The simulation consists of two processes: the openpilot stack and the MetaDrive bridge. Start them in separate terminals.Start openpilot
Launch the openpilot processes using the simulator launch script:This starts all the openpilot daemons configured for simulator use.
Start the MetaDrive bridge
In a second terminal, start the bridge process. The bridge connects the MetaDrive simulator to openpilot’s message bus:A MetaDrive window will open showing a simulated driving environment.
Engage openpilot
With both processes running, use the keyboard controls in the MetaDrive window to interact with the simulation:
Press
| Key | Action |
|---|---|
2 | Engage openpilot (also decreases cruise speed) |
1 | Cruise resume / increase speed |
3 | Cruise cancel |
S | Disengage (simulates a brake press) |
r | Reset simulation |
i | Toggle ignition |
q | Exit all |
w a s d | Manual vehicle control |
2 to engage openpilot, then 1 to increase the cruise speed.Bridge options
The bridge supports several flags for different testing scenarios:| Flag | Description |
|---|---|
--joystick | Control the simulated car with a physical joystick |
--high_quality | Enable higher-quality rendering in MetaDrive |
--dual_camera | Enable a second (wide) camera to simulate the comma three/four dual-camera setup |
Webcam mode
If you want to test openpilot’s vision pipeline with real camera input rather than a simulator,tools/webcam/ provides an alternative. Webcam mode runs openpilot using USB or built-in webcams on your PC as camera inputs — no comma device required.
Tips for simulation development
- Use the
--high_qualityflag when you need accurate visual inputs for testing the vision model. - Use
--dual_cameraif your code paths depend on the wide-angle camera stream. - Combine simulation with the replay tool to test against recorded real-world data alongside synthetic scenarios.
- Run
selfdrive/ui/ui.pyalongside the simulation to see openpilot’s UI overlays in real time.