This document explains the project structure, dependency management, and development environment configuration for openpilot. The configuration is centralized in pyproject.toml, which defines Python dependencies, build system settings, testing configuration, and code quality tools. This page covers the dependencies required for runtime operation, optional dependency groups for development and testing, and the configuration of various tools used in the development workflow.
The openpilot project is configured as a Python package with specific metadata and requirements defined in pyproject.toml.
| Property | Value |
|---|---|
| Package Name | openpilot pyproject.toml2 |
| Python Version | >= 3.12.3, < 3.13 pyproject.toml3 |
| License | MIT License pyproject.toml4 |
| Version | 0.1.0 pyproject.toml5 |
| Description | "an open source driver assistance system" pyproject.toml6 |
The project uses Python 3.12.3+ (as specified in pyproject.toml pyproject.toml3 and .python-version .python-version1) to ensure compatibility with modern language features and pinned dependencies. The build system is configured to use hatchling as the build backend pyproject.toml115-116
Sources: pyproject.toml1-9 pyproject.toml115-116 .python-version1
openpilot uses uv for fast, reproducible dependency management tools/setup_dependencies.sh98-111 Dependencies are managed through a combination of standard packages and local submodules.
The project defines core dependencies organized by system component usage pyproject.toml11-67 These include both standard Python packages and vendored native dependencies.
Sources: pyproject.toml11-67 pyproject.toml104-112 pyproject.toml216-222
The project defines optional dependency groups for specialized workflows pyproject.toml69-99
| Group | Purpose | Key Dependencies |
|---|---|---|
docs | Documentation generation | Jinja2, zensical pyproject.toml70-73 |
testing | CI/CD and local validation | pytest, ruff, codespell, hypothesis pyproject.toml75-88 |
dev | Local development/plotting | matplotlib pyproject.toml90-92 |
tools | Simulation and external tools | comma-deps-imgui, metadrive-simulator pyproject.toml94-99 |
Sources: pyproject.toml69-99
The native code compilation is orchestrated by SCons through SConstruct. It enforces a whitelist of allowed system libraries to ensure reproducibility and prevent silent reliance on host packages SConstruct88-103
The build system detects the target platform to apply specific flags SConstruct45-56:
larch64: Comma 3/3X/4 devices (Linux ARM64 with /TICI file) SConstruct13-50Darwin: macOS ARM64 SConstruct47-48x86_64 / aarch64: Generic Linux PC environments SConstruct53-54Standard flags are applied to ensure strict code quality SConstruct121-168:
-O2 -g (optimized with debug symbols) SConstruct130-132-std=gnu11 (C) and -std=c++1z (C++17) SConstruct142-143-Werror, -Wunused, -Wshadow SConstruct133-135Sources: SConstruct1-212
pytest is configured for high-performance, parallel test execution pyproject.toml126-142
-n auto --dist=loadgroup for multi-core distribution pyproject.toml128cpp_harness.py for C++ tests pyproject.toml130slow for long-running tests and tici for device-only tests pyproject.toml133-134ruff enforces code style and bans problematic APIs pyproject.toml152-195
time.time (prefer time.monotonic), unittest (prefer pytest), and specific pyray calls that can miss events pyproject.toml181-192codespell ensures documentation and code comments are free of typos pyproject.toml144-149 It ignores false positives (e.g., uint, deque, stdio) and skips third-party or generated directories like c_generated_code and onnx models pyproject.toml147-149
Sources: pyproject.toml126-210
The project provides comprehensive .vscode configuration files for a standardized development environment.
settings.json: Configures editor behavior (2-space indent) and excludes virtual environments/caches from search and analysis .vscode/settings.json1-21extensions.json: Recommends essential extensions including Python, C++, Ruff, and Pre-commit .vscode/extensions.json1-8launch.json: Defines debug targets for Python processes (e.g., controlsd.py), C++ processes (e.g., ui), and specialized safety replay debugging .vscode/launch.json1-88A specialized workflow allows debugging C-based safety code replayed from Python logs using LLDB docs/DEBUGGING_SAFETY.md1-21
Sources: .vscode/settings.json1-21 .vscode/launch.json1-88 docs/DEBUGGING_SAFETY.md1-21
The project provides automation for environment setup:
tools/setup_dependencies.sh: Handles system package installation for various Linux distributions (apt, dnf, yum, pacman, etc.) and macOS tools/setup_dependencies.sh22-120 It also installs uv and synchronizes the Python environment tools/setup_dependencies.sh98-111The tools/scripts/dump.py utility (referenced in metadata) is a core debugging tool for real-time message inspection, allowing developers to monitor cereal messages across the system IPC.
Sources: tools/setup_dependencies.sh1-139
Refresh this wiki