Skip to main content

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.

The replay tool is one of the most important utilities in the openpilot developer toolbox. It lets you reproduce any logged drive by publishing all recorded messages back onto the internal message bus, making openpilot’s processes behave as if the drive were happening live. This means you can reproduce bugs, profile algorithms, and iterate on code against real-world data — without a car, comma device, or any road time.

​
Authenticate with your comma account

Before replaying your own routes, authenticate so that the replay tool can fetch routes from the comma servers. 
python3 tools/lib/auth.py
You can skip authentication if you only need the built-in demo route.

​
Replaying a route

No hardware is required to replay a route. This works entirely on your development machine.
Replay publishes logged messages over MSGQ (or ZMQ), mocking the openpilot services that normally produce live data. This lets you run any openpilot process — the UI, model runner, controls — against recorded data.
1

Run the demo route

The quickest way to get started is with the built-in demo route, which requires no authentication:
tools/replay/replay --demo
2

Replay one of your own routes

Find your routes at connect.comma.ai, then pass the route name to replay:
tools/replay/replay '5beb9b58bd12b691/0000010a--a51155e496'
3

Replay a locally stored route

If you have route segments saved on disk, point replay at the directory:
tools/replay/replay "5beb9b58bd12b691/0000010a--a51155e496" --data_dir="/path_to_routes"
4

Visualize in the openpilot UI

While replay is running, launch the UI to see the drive rendered with overlays:
# Terminal 1
tools/replay/replay --demo

# Terminal 2
cd selfdrive/ui && ./ui.py
5

Watch all three cameras simultaneously

Use the --dcam and --ecam flags along with watch3 to view the road, driver, and wide cameras at once:
# Terminal 1
cd tools/replay && ./replay --demo --dcam --ecam

# Terminal 2
cd selfdrive/ui && ./watch3.py
6

Stream data into plotjuggler

For signal-level analysis, stream replay output into plotjuggler:
# Terminal 1
tools/replay/replay --demo

# Terminal 2
tools/plotjuggler/juggle.py --stream

​
Useful replay options

tools/replay/replay -h
FlagDescription
--demoUse the built-in public demo route
-s <seconds>Start playback from a specific offset
-x <speed>Set playback speed (0.2–3×)
--dcamLoad driver camera stream
--ecamLoad wide road camera stream
--no-loopStop at the end of the route instead of looping
-b <services>Block specific services from being published
-a <services>Only publish the specified services

​
ZMQ mode

By default, replay sends messages over MSGQ. To use ZMQ instead: 
ZMQ=1 tools/replay/replay --demo

​
Replaying CAN data

CAN replay requires a panda jungle and a comma four device. This is for testing that your code works with real hardware in the loop.
CAN replay sends raw CAN messages back onto the car’s bus using a panda jungle — a device with six OBD-C ports for connecting multiple comma devices simultaneously. This lets you run a comma device as if it were physically installed in a car, without needing to be in the car.
1

Connect the hardware

Connect the panda jungle to your PC via USB. Connect a comma four (or a panda) to one of the jungle’s OBD-C ports.
2

Run can_replay.py

From the tools/replay/ directory, run can_replay.py with a route name. If no route is specified, a default public route is used:
cd tools/replay
./can_replay.py '5beb9b58bd12b691/0000010a--a51155e496'
The script replays CAN messages in a loop to all connected pandas and jungles.
3

Observe device behavior

The comma device connected to the jungle will see CAN traffic as if it were installed in the original car. You can observe how your firmware changes respond to the recorded signals.
CAN replay puts real CAN messages onto the bus. Only connect a comma device or panda to the jungle — never connect a real car during CAN replay.

Build docs developers (and LLMs) love

Get started for freeTalk to us