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.
Ubuntu 24.04 is the primary development target for openpilot, and all CI runs against it. Most of openpilot also works natively on macOS. On Windows, WSL2 provides a near-native Ubuntu experience and is the recommended path for Windows developers. Running natively on any other system is not currently supported.
openpilot requires Python 3.12.3 (up to, but not including, 3.13). The build system is SCons.
Setup
Ubuntu 24.04
macOS
Windows (WSL2)
Clone the repository
git clone https://github.com/commaai/openpilot.git
cd openpilot
Run the setup script
The setup script installs all system dependencies and creates a Python virtual environment under .venv/: Activate the Python virtual environment
All Python tooling must run inside the virtual environment:source .venv/bin/activate
~/.bashrc to activate the environment automatically in new shells. Build openpilot
openpilot uses SCons as its build system. The -u flag runs the build from any subdirectory:The first build takes several minutes. Subsequent builds are incremental. Clone the repository
git clone https://github.com/commaai/openpilot.git
cd openpilot
Run the setup script
The same setup script works on macOS and handles macOS-specific dependencies: Activate the Python virtual environment
source .venv/bin/activate
Some openpilot components are Linux-only and will not build or run on macOS. The core tools, replay, and most Python utilities work without issues.
Install WSL2 with Ubuntu 24.04
Open PowerShell as Administrator and run:wsl --install -d Ubuntu-24.04
Open an Ubuntu WSL2 terminal
Launch Ubuntu 24.04 from the Start menu or run wsl in PowerShell.
Clone the repository
Run the following inside your WSL2 Ubuntu environment:git clone https://github.com/commaai/openpilot.git
cd openpilot
Activate the Python virtual environment
source .venv/bin/activate
Configure GPU acceleration for GUI apps (optional)
If you experience performance issues with the UI or simulator, enable hardware acceleration by adding the following to your ~/.bashrc:export GALLIUM_DRIVER=d3d12
Verify the setup
After building, confirm everything is working by running the unit tests:
Project structure
The tools/ directory contains the developer utilities you will use most often:
tools/
├── cabana/ # View and plot CAN messages from drives or in realtime
├── camerastream/ # Stream cameras over the network
├── joystick/ # Control your car with a joystick
├── lib/ # Libraries for reading openpilot logs
├── plotjuggler/ # Plot openpilot logs
├── replay/ # Replay drives and mock openpilot services
├── scripts/ # Miscellaneous scripts
├── serial/ # Tools for the comma serial
├── sim/ # Run openpilot in a simulator
└── webcam/ # Run openpilot on a PC with webcams
Learn the openpilot ecosystem hands-on by playing the CTF. It walks through many of the tools and workflows used in day-to-day development. 