Environment:CARLA simulator Carla Python API Runtime

Knowledge Sources	CARLA Simulator CARLA Python API
Domains	Infrastructure, Autonomous_Driving
Last Updated	2026-02-15 07:00 GMT

Overview

Python 3 runtime environment with numpy < 2.0, networkx, pygame, and the CARLA Python API wheel for running simulations, agents, and examples.

Description

This environment defines the Python runtime dependencies needed to use the CARLA Python API client. The CARLA Python API is a compiled C++ extension module (built via Boost.Python) that connects to the CARLA simulator server over RPC. The Python agent stack (BasicAgent, BehaviorAgent, GlobalRoutePlanner) requires additional packages including networkx for graph-based route planning and shapely for polygon intersection in obstacle detection. Example scripts additionally need pygame for visualization and open3d for point cloud rendering.

Usage

Use this environment for any client-side CARLA scripting: connecting to the simulator, spawning actors, configuring traffic, running autonomous agents, collecting sensor data, and recording/replaying simulations. This is the mandatory prerequisite for all Python-based implementations across workflows 1-5 (Simulation Setup, Traffic Generation, Autonomous Navigation, Sensor Data Collection, Recording and Replay).

System Requirements

Category	Requirement	Notes
OS	Ubuntu 22.04 or Windows 11	Same as simulator requirements
Python	Python 3 (3.8+)	PythonAPI/CMakeLists.txt requires Python3 with Interpreter, Development.Module, Embed, SABIModule
Network	TCP access to CARLA server on port 2000	Default server port; configurable via Client constructor
GPU	Not required for client	Client is CPU-only; GPU needed only for the CARLA server

Dependencies

Core CARLA API

From PythonAPI/carla/requirements.txt:

`networkx` (graph library for GlobalRoutePlanner A* routing)
`numpy` >= 1.24.4, < 2.0 (array operations; numpy 2.x breaks Boost.Python bindings)

Agent Dependencies (implicit)

From PythonAPI/carla/agents/navigation/basic_agent.py:13:

`shapely` (Polygon geometry for bounding box obstacle detection)

Example Scripts

From PythonAPI/examples/requirements.txt:

`numpy` >= 1.24.4, < 2.0
`pygame` (visualization and HUD rendering)
`open3d` (point cloud visualization; Python <= 3.11 only)
`Pillow` (image processing)

Utility Scripts

From PythonAPI/util/requirements.txt:

`numpy` >= 1.24.4, < 2.0
`psutil` (system monitoring)
`py-cpuinfo` (CPU information)
`pygame`
`python-tr`

Documentation Generation

From PythonAPI/docs/requirements.txt:

`pyyaml`

Testing

From PythonAPI/test/requirements.txt:

`nose2` (test runner)
`opencv-python` (image comparison)

Credentials

No credentials required for the Python API runtime. The CARLA server must be running and accessible on the configured host/port (default: `localhost:2000`).

Quick Install

# Install core CARLA API dependencies
pip install "numpy<2.0,>=1.24.4" networkx shapely

# Install example script dependencies
pip install pygame Pillow "open3d; python_version<='3.11'"

# Install utility dependencies
pip install psutil py-cpuinfo python-tr

# Install the CARLA Python API (after building from source)
cmake --build Build --target carla-python-api-install

Code Evidence

Numpy version constraint from PythonAPI/CMakeLists.txt:11-29:

# -- Temporary check for numpy 2 presence, which breaks our current version of Boost.Python.
execute_process (
  COMMAND
    ${Python3_EXECUTABLE}
      -c
      "import numpy; print(numpy.__version__)"
  OUTPUT_VARIABLE NUMPY_VERSION_STRING
)
if ("${NUMPY_VERSION_STRING}" VERSION_GREATER "2.0.0")
  carla_error ("Unsupported Numpy version, please downgrade to a version prior to numpy 2.")
endif ()

Shapely import for obstacle detection from PythonAPI/carla/agents/navigation/basic_agent.py:13:

from shapely.geometry import Polygon

NetworkX import for route planning from PythonAPI/carla/agents/navigation/global_route_planner.py:13:

import networkx as nx

Open3d Python version constraint from PythonAPI/examples/requirements.txt:3:

open3d; python_version <= '3.11'

Common Errors

Error Message	Cause	Solution
`ImportError: No module named 'carla'`	CARLA Python API not installed	Run `cmake --build Build --target carla-python-api-install` or `pip install` the built wheel
`Unsupported Numpy version`	Numpy 2.x installed	`pip install "numpy<2.0,>=1.24.4"`
`ImportError: No module named 'shapely'`	Shapely not installed (needed by BasicAgent)	`pip install shapely`
`RuntimeError: time-out of 2000ms while waiting for the simulator`	CARLA server not running or wrong host/port	Start CARLA server first; check `--host` and `--port` arguments
`open3d` install fails on Python 3.12+	open3d does not support Python > 3.11	Use Python 3.11 or skip open3d examples

Compatibility Notes

Numpy < 2.0: This is a hard constraint due to Boost.Python ABI incompatibility with numpy 2. The check is enforced at CMake configure time (PythonAPI/CMakeLists.txt:27-29).
open3d: Only available for Python <= 3.11. Point cloud visualization examples will not work on newer Python versions.
shapely: Required only if using BasicAgent with bounding box detection (`use_bbs_detection=True`) or when the ego vehicle is at a junction or invading opposite lanes.
Client-server model: The Python API is a thin client that communicates with the CARLA server via RPC. The server must be running before any client script can connect.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment