Principle:CARLA simulator Carla Python API Build

Knowledge Sources	CARLA Simulator CARLA Documentation
Domains	Build_System, Development
Last Updated	2026-02-15 00:00 GMT

Overview

Building the CARLA Python API creates the Python/C++ bridge that allows users to control the simulator, spawn actors, read sensors, and manage traffic from Python scripts.

Description

The CARLA Python API is the primary interface through which researchers, developers, and autonomous driving systems interact with the CARLA simulator. It is built as a native Python extension module that bridges Python code to the underlying C++ client library (LibCarla). The build process compiles the C++ client code, links it with Boost.Python to create Python-callable bindings, and packages the result as a pip-installable Python wheel.

The build is triggered via the CMake target carla-python-api-install, which orchestrates several sub-steps:

1. Compile the carla-client C++ library (networking, serialization, actor management)
2. Compile the Boost.Python bindings that wrap C++ classes as Python objects
3. Link against NumPy C API for efficient sensor data transfer (images, point clouds)
4. Package the compiled extension module into a Python wheel (.whl) file
5. Install the wheel into the active Python environment

Usage

This principle applies when:

• Building CARLA from source and needing the Python client to connect to the simulator
• Developing or extending the Python API with new functionality
• Debugging C++ to Python type conversion issues
• Setting up a Python development environment for CARLA scripting

Theoretical Basis

C++/Python interoperability: CARLA's simulation engine runs as a C++ server process. Users interact with it through a client-server architecture where the Python API serves as the client. The challenge is bridging the performance-critical C++ codebase with the ergonomic Python scripting interface. CARLA uses Boost.Python for this bridge, which provides:

• Automatic type conversion between C++ and Python types
• Class wrapping that exposes C++ classes as Python classes with methods and properties
• Exception translation between C++ exceptions and Python exceptions
• Support for Python inheritance from C++ base classes

Boost.Python vs alternatives: While modern alternatives like pybind11 exist, CARLA uses Boost.Python due to its deep integration with the Boost library ecosystem (which CARLA already depends on for networking via Boost.Asio and serialization). Boost.Python provides mature, battle-tested bindings with comprehensive support for complex C++ features.

NumPy integration: Sensor data in CARLA (camera images, LIDAR point clouds, radar returns) consists of large numerical arrays. The Python API uses NumPy's C API to create zero-copy or minimal-copy data transfers from the C++ sensor buffers to Python NumPy arrays. This is critical for performance: a single camera frame at 1920x1080 resolution contains over 6 million pixel values, and copying this data inefficiently would create an unacceptable bottleneck.

Wheel packaging: The build produces a standard Python wheel (.whl) file that can be installed via pip. This provides several benefits:

• Standard installation mechanism that works with virtual environments
• Dependency metadata (the wheel can declare its Python package dependencies)
• Platform tags that ensure the compiled extension is matched to the correct OS and Python version
• Easy distribution and sharing of the built API

Build dependency chain: The Python API build depends on:

• carla-client: The C++ client library with networking and actor management
• Boost::python: The C++ to Python binding library
• numpy: NumPy headers for C API integration
• libcarla: Core CARLA types and data structures

All of these are resolved through CARLA's CMake build system, which ensures the correct versions and ABI-compatible builds.

Practical Guide

Step 1: Ensure CMake configuration is complete

The CMake configuration step (see CMake_Build_Configuration) must have been run successfully before building the Python API.

Step 2: Build the Python API

cd CarlaUE5
cmake --build Build --target carla-python-api-install

This command:

• Compiles the C++ client library
• Builds the Boost.Python extension module
• Creates a wheel file
• Installs the wheel into the current Python environment

Step 3: Verify the installation

python3 -c "import carla; print(carla.__version__)"

Step 4: Test basic connectivity

# With a running CARLA server:
python3 -c "
import carla
client = carla.Client('localhost', 2000)
print('Connected to CARLA', client.get_server_version())
"

Related Pages

Implemented By

• Implementation:CARLA_simulator_Carla_CMake_Build_Python_API