Implementation:CARLA simulator Carla CMake Build Python API
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Development |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Concrete tool for building and installing the CARLA Python API client library as a pip-installable wheel in the CARLA build pipeline.
Description
This implementation invokes the CMake build target carla-python-api-install to compile the CARLA Python/C++ client library, create Boost.Python bindings, package the result as a Python wheel, and install it into the active Python environment. The target is defined in PythonAPI/CMakeLists.txt and orchestrates the full compilation and packaging pipeline.
The resulting Python package provides the carla module, which contains all client-side classes for connecting to the simulator, spawning actors, configuring sensors, controlling traffic, and managing simulation state.
Usage
Run this command after completing the CMake configuration step. The Python API must be built before running any CARLA Python scripts or examples. Rebuild when the C++ client code changes or when switching Python versions.
Code Reference
Source Location
- Repository: CARLA
- File:
PythonAPI/CMakeLists.txt:L177-188,CarlaSetup.sh:L140-142
Signature
cmake --build Build --target carla-python-api-install
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
Build |
Directory path | Yes | The CMake build directory created during the configuration step (contains build.ninja and CMakeCache.txt).
|
--target carla-python-api-install |
Target name | Yes | The CMake target that builds and installs the Python API wheel. |
| CMake configuration | Prerequisite | Yes | The CMake configuration step must have completed successfully. |
| Python 3 interpreter | System tool | Yes | A Python 3.8+ interpreter with pip available. The wheel is installed into this interpreter's site-packages. |
| Boost.Python | Library | Yes | Resolved by CMake during configuration; used for C++ to Python bindings. |
| NumPy | Python package | Yes | Required for C API headers during compilation and as a runtime dependency. |
Outputs
| Name | Type | Description |
|---|---|---|
carla Python package |
Installed package | The CARLA Python module installed into the active Python environment's site-packages. |
| Wheel file | .whl file |
A pip-installable wheel file in the build directory, suitable for redistribution. |
carla-client shared library |
.so file |
The compiled C++ client library linked into the Python extension module. |
| Exit code | Integer | 0 on successful build and installation; non-zero on compilation or packaging failure.
|
Usage Examples
Basic Example
# Navigate to the CARLA repository root
cd CarlaUE5
# Build and install the Python API
cmake --build Build --target carla-python-api-install
# Verify the installation
python3 -c "import carla; print(carla.__version__)"
Building with Verbose Output
# Use --verbose flag for detailed compilation output (useful for debugging build errors)
cmake --build Build --target carla-python-api-install --verbose
Building with Parallel Jobs
# Specify the number of parallel compilation jobs
cmake --build Build --target carla-python-api-install -j$(nproc)
Installing into a Virtual Environment
# Create and activate a virtual environment before building
python3 -m venv carla-venv
source carla-venv/bin/activate
# Build and install -- the wheel will be installed into the venv
cmake --build Build --target carla-python-api-install
# Verify within the venv
python3 -c "import carla; print(carla.__version__)"
Installing the Wheel Manually
# If you prefer manual installation, find the built wheel
find Build -name "carla-*.whl"
# Install it with pip
pip install Build/path/to/carla-*.whl