Installation Guide¶
Prerequisites¶
- Windows 10/11 (64-bit)
- Python 3.12 for the root Windows manifest, or Python 3.10 if you intentionally select the backup manifest
- CUDA 12.8 (for GPU acceleration)
- CARLA 0.9.15 / 0.9.16 / 0.10.0
- Git
Before installing, check the CARLA Version Support matrix and choose the Windows manifest that matches your CARLA wheel and Python ABI.
Step 1: Clone Repository¶
Step 2: Install Pixi¶
If you don't have pixi installed:
# Install pixi (Windows)
powershell -c "irm https://pixi.sh/install.ps1 | iex"
# Linux/macOS
curl -fsSL https://pixi.sh/install.sh | sh
Step 3: Setup Environment¶
# Default root manifest on Windows: CARLA 0.9.16 + Python 3.12
# Alternative Windows manifests live in dependencies/pixi/
# pixi_win_py310_carla0915_backup.toml
# pixi_win_py312_carla0915.toml
# pixi_win_py312_carla0916.toml
# pixi_win_py312_carla0100_experimental.toml
#
# Linux remains on Python 3.10 because the bundled Linux CARLA wheel is cp310.
# Linux ROCm users should still use dependencies/pixi/pixi_Linux_ROCm.toml
# Install all dependencies
pixi install
# Test the installation: the test suite, the plugin registry, the SUMO
# bindings and a short SUMO run -- no CARLA server needed
pixi run verify
Windows manifest summary:
pixi.toml: default Windows experiment pathCARLA 0.9.16 + Python 3.12dependencies/pixi/pixi_win_py310_carla0915_backup.toml: backupCARLA 0.9.15 + Python 3.10dependencies/pixi/pixi_win_py312_carla0915.toml: win-onlyCARLA 0.9.15 + Python 3.12, backed by a locally built Windows wheeldependencies/pixi/pixi_win_py312_carla0916.toml: explicitCARLA 0.9.16 + Python 3.12dependencies/pixi/pixi_win_py312_carla0100_experimental.toml: experimentalCARLA 0.10.0 + Python 3.12
Step 4: Install CARLA¶
- Download the CARLA version that matches your chosen Windows manifest:
0.9.16for the default Windows path0.9.15for the compatibility manifests0.10.0only for import-level experiments- Extract to a folder (for example
D:\Applications\CARLA_0.9.16,D:\Applications\CARLA_0.9.15, orD:\Applications\Carla-0.10.0-Win64-Shipping) - Point the environment at it. The root manifest's Windows activation
(
[target.win-64.activation.env]inpixi.toml) setsCARLA_ROOT,CARLA_HOMEandCARLA_BINto the example locationD:\Applications\CARLA_0.9.16, and activation overrides values set in your shell, so when CARLA lives elsewhere edit those three lines inpixi.toml(the matrix launcher also takes--carla-root/--carla-bin). Outside pixi, set the variable yourself:
CARLA_0.9.15 or CARLA_0.9.16 folder.
Linux servers: download the Linux release (CARLA_0.9.16.tar.gz from the
official CARLA release bucket, ~8.3 GB) and extract it on a local disk
(not NFS). The pixi activation expects /opt/CARLA_0.9.16; if it lives
elsewhere, edit the [target.linux-64.activation.env] lines in pixi.toml
(activation overrides shell values) or pass --carla-bin
/path/to/CarlaUE4.sh to the launchers. The bundled Linux client wheel needs glibc ≥ 2.31
(declared in pixi.toml), and pixi install --locked needs pixi ≥ 0.73
(lock-file format 7). Keep the environment itself on local disk too:
pixi config set --local detached-environments /local/path before
pixi install when the checkout is on a network home directory.
Notes:
0.9.16is the main follow-up candidate for current OpenCDA-MARL workflows.0.10.0is not a supported project runtime yet. Keep it limited to import and capability smoke tests until Traffic Manager, SUMO co-simulation, V2X, Town05/Town06, and custom map workflows are revalidated.- The root Windows manifest now points to
0.9.16 + Python 3.12for ongoing experiments. - Keep
dependencies/pixi/pixi_win_py310_carla0915_backup.tomlas the immediate fallback if scenario regression reveals a3.12incompatibility.
Step 5: Verify Installation¶
# Run CARLA server (in one terminal)
cd $env:CARLA_HOME
.\CarlaUE4.exe
# Or manually start the server by clicking the CarlaUE4.exe file
# Run OpenCDA test (in another terminal)
pixi run marl-quick-test
Recommended Windows verification order:
CARLA 0.9.16 + Python 3.12root experiment pathCARLA 0.9.15 + Python 3.12compatibility manifestCARLA 0.9.15 + Python 3.10backup manifestCARLA 0.10.0 + Python 3.12import-only experiment
Development Environment¶
For documentation development:
# Activate docs environment
pixi shell -e docs
# Serve documentation locally
pixi run -e docs docs-serve
Known issues¶
- CARLA connection errors: the server must be running before the client
starts (
CarlaUE4 -RenderOffScreenon a headless machine); the matrix launcher starts and restarts servers itself. - Perception with
--apply_mlloads YOLOv8 from theultralyticspackage (the pixi environment installs it; theyolov8m.ptweights download on first use). Only when that package is missing does it fall back to YOLOv5 throughtorch.hub; on recent PyTorch a cachedmodels/common.pyfrom before Ultralytics' fix then raisesExpected 'device_type' of type 'str', got: '<class 'bool'>': delete the cached hub folder (~/.cache/torch/hub/ultralytics_yolov5_master) sotorch.hubfetches the current YOLOv5 source, which passes the device type toautocast. That code is Ultralytics' (AGPL-3.0) and is not part of this repository. - A stale pixi environment after a lock change:
pixi clean cachethenpixi install. libsumo import failed ...; falling back to traci: SUMO then runs over TraCI, about 13× slower per step. A pixi environment declareslibsumo, sopixi installrestores it. After a pip install of the wheel, install the binding that matches the bundled SUMO, as the warning says:pip install libsumo==<SUMO version>(the warning fills in the version of the SUMO binary it found).OPENCDA_SUMO_LIB=traciselects TraCI and silences the warning.- A system SUMO on the same machine (named by
SUMO_HOME, or by aPYTHONPATHentry for itstoolsdirectory) is ignored while the environment'seclipse-sumopackage is installed: the engine uses that package's binary and bindings and drops every other SUMOtoolsdirectory fromsys.path, so the client and the server always match.SUMO_HOMEis used only when the package is absent.
Getting help¶
- Search existing issues
- Open a new issue with the scenario reference, the command and the log lines around the failure