Skip to content

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.04 and ubuntu-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-setup refuses to download the nightly there.

Python Version

  • Python 3.10 – 3.14 — pyproject.toml declares requires-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 with python --version.
  • scenario-setup needs Python 3.10.12, 3.11.4 or 3.12+ — it unpacks CARLA with tarfile'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 set CARLA_EXECUTABLE.
  • Hydra on Python 3.14 — Hydra 1.3 gives --shell-completion a help object that Python 3.14's argparse refuses ("badly formed help string"), so a @hydra.main command would fail before it parses anything (#692). autoware_carla_scenario.hydra_compat works around it: the scenario entry point and the lanelet sweeper import it, and it has Hydra build its parser with an ArgumentParser subclass that skips argparse's check for help that is not a string (argparse itself is left as it is, and --hydra-help still shows the completion instructions). On Python 3.10 to 3.13 importing it changes nothing. A @hydra.main app 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.

uv run typesafe-codon 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:

curl -LsSf https://astral.sh/uv/install.sh | sh

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)

  1. Clone the repository:

    git clone https://github.com/autowarefoundation/autoware_carla_scenario.git
    cd autoware_carla_scenario
    
  2. Sync dependencies from the lock file:

    uv sync
    

    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

python -c "import autoware_carla_scenario; print('Installation successful!')"

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 in typesafe-carla-toolchain
  • pyxodr>=0.1.0 — OpenDRIVE parser used by MapManager / to_opendrive
  • opencv-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.21
  • pytest>=9.0.1
  • mypy>=1.19.0 — the static check's None check (scenario-check)
  • python-dotenv>=1.2.2
  • simple-lanelet2>=1.2.3 — the Lanelet2 binding, plus the Autoware regulatory-element extensions, as a single wheel
  • tqdm>=4.67.1
  • hydra-core>=1.3.2, omegaconf>=2.3.0
  • fastapi>=0.115.0, uvicorn[standard]>=0.34.0, jinja2>=3.1.0 — result viewer
  • python-multipart>=0.0.9 — reads the Scenario Editor's form posts
  • pyyaml>=6.0, pydantic>=2.0.0
  • openodd-py>=0.47.1 — ASAM OpenODD: the ODD model, the sampler and coverage; this package is its CARLA backend
  • packaging>=23.0, tomli>=1.1.0 (Python < 3.11) — read a scenario package's requires-python for its wheelhouse
  • carla-driver-interface>=2.4.2,<3, grpcio>=1.60, protobuf>=4.25.0,<8 — the gRPC contract to an external driver policy
  • orjson>=3.13.0 — serialises the trajectory log

Troubleshooting

Import Errors

Ensure that:

  1. You're using a supported Python (see Python Version).
  2. The package was installed in your active environment (uv sync from the repository root, or a fresh uv venv followed by uv sync).
  3. If you see ImportError: ... lanelet2 ..., a lanelet2 distribution from PyPI may be shadowing the one simple-lanelet2 provides. Reset the environment with rm -rf .venv && uv sync --dev.

CARLA Connection Issues

If you cannot connect to the CARLA simulator:

  1. Ensure the CARLA server is running.
  2. Check that your overrides match: server.host, server.port, traffic_manager.port.
  3. Verify network connectivity to the CARLA server.

Next Steps

Once installed, see the Usage Guide to run scenarios.