Installation¶
This guide will help you install the autoware-carla-scenario package.
System Requirements¶
Operating System¶
- Linux x86_64 or aarch64 (Ubuntu 22.04 is the reference; CI runs on
ubuntu-24.04andubuntu-24.04-arm). Every runtime dependency resolves to a wheel on both, the CARLA client's CPython package included (see CARLA client), so nothing is compiled on install. - On aarch64 the framework, its CARLA client and the static check all run,
but CARLA itself does not: its server is built for x86_64 only. Run the
server on an x86_64 host and point the runner at it with
server.host=<address>(the server already listening there is used; the runner launches CARLA only for a local host, see CARLA Simulator);scenario-setuprefuses to download the nightly there.
Python Version¶
- Python 3.10 – 3.14 —
pyproject.tomldeclaresrequires-python = ">=3.10,<3.15": the interpreters CI tests. No dependency caps it any more; it is raised together with CI's interpreter matrix. Check your version withpython --version. scenario-setupneeds Python 3.10.12, 3.11.4 or 3.12+ — it unpacks CARLA withtarfile's extraction filters, which earlier patch releases lack (Ubuntu 22.04 released with 3.10.4; its updates bring 3.10.12, so an updated 22.04 is fine); there it stops with a message rather than unpacking without them. Upgrade Python, or install CARLA another way and setCARLA_EXECUTABLE.- Hydra on Python 3.14 — Hydra 1.3 gives
--shell-completiona help object that Python 3.14's argparse refuses ("badly formed help string"), so a@hydra.maincommand would fail before it parses anything (#692).autoware_carla_scenario.hydra_compatworks around it: thescenarioentry point and the lanelet sweeper import it, and it has Hydra build its parser with anArgumentParsersubclass that skips argparse's check for help that is not a string (argparse itself is left as it is, and--hydra-helpstill shows the completion instructions). On Python 3.10 to 3.13 importing it changes nothing. A@hydra.mainapp of your own that runs on 3.14 imports it before calling the decorated function:import autoware_carla_scenario.hydra_compat # noqa: F401.
CARLA Simulator¶
The framework targets CARLA UE5 (0.10.0 and ue5-dev). CARLA 0.9.x (UE4)
is not supported. uv run scenario-setup downloads CARLA's nightly Linux
build into ~/.autoware_carla_scenario/bin/carla, and the runner launches it
from there (see the Quick Start). A CARLA installed any other
way is used through CARLA_EXECUTABLE. Ctrl-C during the download or the
unpack prints scenario-setup: interrupted and exits 130, leaving no partial
install behind.
The runner launches CARLA only for a local server.host: localhost
(or a *.localhost name), a loopback address (127.0.0.0/8, ::1), this
machine's own host name, or any name or address that resolves to one of this
machine's interface addresses (its LAN address, 0.0.0.0). For any other
host it uses the server already listening at server.host:server.port, and
when none answers there it stops at once with No CARLA server reachable at
<host>:<port>; the runner only launches CARLA for a local host rather than
launching one here, which could never answer at the remote address. Nor does
a run restart a remote server that goes away: a run it drops fails, as on any
server the runner did not launch itself. Start the remote server first, and
check server.host and server.port when the message appears.
CARLA client¶
The Python client is
typesafe_carla, a plain
dependency of the package (typesafe-carla>=0.8.1,<0.9, from PyPI, Linux
x86_64 and aarch64), imported as import typesafe_carla.carla as carla. It also
provides the Codon library the static check compiles scenarios against, and
pulls in typesafe-carla-toolchain, the pinned Codon compiler. The official
carla wheels are not used, and no extra has to be requested.
The released wheel on PyPI carries its CPython package prebuilt
(typesafe_carla/carla/_prebuilt), one build that serves every Python 3.10+,
so uv sync (or pip install) is the whole installation: nothing is
compiled, no C compiler is needed, and nothing is fetched beyond the install
itself.
Only where no matching prebuilt package exists -- typesafe_carla installed
from a source checkout or an sdist, edited Codon sources, or a
typesafe-carla-toolchain release other than the one the wheel was built
with -- does the first import typesafe_carla.carla build it instead. That
build takes 15 to 50 minutes and about 14 GB of RAM, needs a C compiler
(cc), and lands in ~/.cache/typesafe_carla/pycarla.
runs it ahead of time, and reports that there is nothing to build when the
prebuilt package applies. Set TYPESAFE_CARLA_PYCARLA_DIR to put the build
elsewhere (a directory set this way is used in preference to the prebuilt
package), and TYPESAFE_CARLA_PYCARLA_BUILD=0 to make a missing build an
ImportError instead of starting one.
Package Manager¶
- uv (version 0.9.7+) — modern Python package manager, used as both the build backend and the workflow runner.
Installing uv¶
If you don't have uv installed yet:
For more options, see the official uv documentation.
Installing the Package¶
The framework does not depend on
autoware_lanelet2_to_opendrive,
the converter that typically produces its OpenDRIVE maps: a Lanelet2 map and an
OpenDRIVE map are loaded as two independent coordinate systems. Install the
converter separately when you need to generate a map.
For Developers (Editable Installation)¶
-
Clone the repository:
-
Sync dependencies from the lock file:
The CARLA client arrives with its CPython package prebuilt; nothing more to build (see CARLA client).
Note
The Lanelet2 binding comes from
simple-lanelet2
as a prebuilt wheel, so uv sync needs no apt packages and no C++
toolchain on any host, and the CARLA client's prebuilt CPython package
means no cc either.
From a Wheel¶
A wheel installed outside a checkout (pip install, uv pip install) does
not carry the built-in Nishishinjuku map's files. Its map config falls back
to data/nishishinjuku.osm and data/nishishinjuku_carla.xodr, resolved
against the current directory, so they are found only from the repository
root. Anywhere else, point at the files with NISHISHINJUKU_LANELET2_PATH and
NISHISHINJUKU_XODR_PATH (see Environment Configuration),
or pass map.lanelet2_path= and map.xodr_path= on the command line.
The editor's new scenarios name the same relative files, never the variables'
values: a scenario document is exported into packages that run on other
machines. A run on the built-in map still reads the variables, because the
map group, composed after the scenario, wins over the paths a document names.
Environment Configuration¶
Configure your environment by exporting the variables consumed by the
package, or by loading a .env file (the package depends on
python-dotenv): the first .env found from the working directory up
is loaded when autoware_carla_scenario.server is imported, wherever the
package is installed, and an exported variable wins over the file. In a
checkout of this repository that is a .env at its root (copy
autoware_carla_scenario/.env.example there), found from anywhere inside it.
Since the file can set CARLA_EXECUTABLE, the program the runner launches,
run the framework only from a directory whose .env (and its parents') you
trust. The most common variables:
| Variable | Required | Description |
|---|---|---|
CARLA_EXECUTABLE |
optional | Path to CarlaUnreal.sh, for a CARLA that scenario-setup did not install. Unset, the installed one is launched; pytest's CARLA tests skip when there is neither and no server answers at their host. |
AUTOWARE_CARLA_SCENARIO_HOME |
optional | Moves ~/.autoware_carla_scenario, where scenario-setup installs CARLA (bin/carla). |
NISHISHINJUKU_MAP_PATH |
when overwriting the built-in .xodr |
Path inside the CARLA install where the original .xodr lives. |
NISHISHINJUKU_XODR_PATH |
outside a checkout | Override the default OpenDRIVE file resolved in conf/map/nishishinjuku.yaml. |
NISHISHINJUKU_LANELET2_PATH |
outside a checkout | Override the default Lanelet2 .osm path (data/nishishinjuku.osm, relative to the current directory). |
VIEWER_BASE_PATH, VIEWER_HOST, VIEWER_PORT, VIEWER_CACHE_DIR, VIEWER_RERUN_WEB_VIEWER, VIEWER_RERUN_MAP_DIR |
optional | viewer web-app overrides (viewer --help for the flags that win over them). |
See the Usage Guide and Architecture for the full list.
Verifying Installation¶
This works without CARLA — running an actual scenario additionally
requires a CARLA server: a live one, or one to launch (scenario-setup, or
CARLA_EXECUTABLE).
Dependencies¶
The package's runtime dependencies (declared in pyproject.toml):
typesafe-carla>=0.8.1,<0.9(Linux x86_64 and aarch64) — the CARLA client and its Codon library; pulls intypesafe-carla-toolchainpyxodr>=0.1.0— OpenDRIVE parser used byMapManager/to_opendriveopencv-python-headless>=4.8— JPEG (and PNG) encoding of the camera frames sent to a driver policy and to HILS devices (headless: the package makes no GUI calls)numpy>=1.21pytest>=9.0.1mypy>=1.19.0— the static check's None check (scenario-check)python-dotenv>=1.2.2simple-lanelet2>=1.2.3— the Lanelet2 binding, plus the Autoware regulatory-element extensions, as a single wheeltqdm>=4.67.1hydra-core>=1.3.2,omegaconf>=2.3.0fastapi>=0.115.0,uvicorn[standard]>=0.34.0,jinja2>=3.1.0— result viewerpython-multipart>=0.0.9— reads the Scenario Editor's form postspyyaml>=6.0,pydantic>=2.0.0openodd-py>=0.47.1— ASAM OpenODD: the ODD model, the sampler and coverage; this package is its CARLA backendpackaging>=23.0,tomli>=1.1.0(Python < 3.11) — read a scenario package'srequires-pythonfor its wheelhousecarla-driver-interface>=2.4.2,<3,grpcio>=1.60,protobuf>=4.25.0,<8— the gRPC contract to an external driver policyorjson>=3.13.0— serialises the trajectory log
Troubleshooting¶
Import Errors¶
Ensure that:
- You're using a supported Python (see Python Version).
- The package was installed in your active environment (
uv syncfrom the repository root, or a freshuv venvfollowed byuv sync). - If you see
ImportError: ... lanelet2 ..., alanelet2distribution from PyPI may be shadowing the onesimple-lanelet2provides. Reset the environment withrm -rf .venv && uv sync --dev.
CARLA Connection Issues¶
If you cannot connect to the CARLA simulator:
- Ensure the CARLA server is running.
- Check that your overrides match:
server.host,server.port,traffic_manager.port. - Verify network connectivity to the CARLA server.
Next Steps¶
Once installed, see the Usage Guide to run scenarios.