Install ScenarioRunner
Paths. scripts/… and references/… below are relative to the
directory holding this SKILL.md. Your working directory is the user's
project, not that directory, so prefix them with its absolute path or the
command is not found.
ScenarioRunner is pure Python — there is nothing to build. Installing it is
three decisions and one pip install:
- which branch matches your CARLA (this is the whole problem),
- where the checkout lives (
SCENARIO_RUNNER_ROOT),
- what goes on
PYTHONPATH.
Get the branch wrong and the failure is not a version warning — it is
Scenario 'X' not supported, a missing map, or a scenario that spawns nothing,
because the scenario classes, the town names and the vehicle blueprints all
changed between branches.
Instructions
Progress:
- [ ] Step 1: Identify the CARLA version in play
- [ ] Step 2: Pick the branch from the matrix
- [ ] Step 3: Clone or check out that branch
- [ ] Step 4: Install requirements into the interpreter that has `carla`
- [ ] Step 5: Record `SCENARIO_RUNNER_ROOT` with `set_config`, then verify (bash scripts/check_env.sh)
Step 1-2: Which branch
python3 scripts/install_scenario_runner.py detect # what CARLA is here?
python3 scripts/install_scenario_runner.py plan # -> branch + exact commands
detect reads the installed carla client, the running server if there is one,
and any SCENARIO_RUNNER_ROOT already present. plan turns that into a branch
recommendation and prints the commands rather than running them.
| Your CARLA | ScenarioRunner branch | Notes |
|---|
| 0.9.14 / 0.9.15 / 0.9.16 (UE4) | master | the live branch; 0.9.16 released Sep 2025 |
| 0.10.0 / 1.0 (UE5) | ue5-master | Town10HD_Opt only; 11 of 101 configs ported; forked Jun 2024. The UE5 line reports 0.10.0 before the 1.0 release and 1.x after; the same branch is the match for both until scenario_runner publishes a 1.0 branch — check its branch list first |
| leaderboard build (0.9.14+large maps) | leaderboard-2.1 or leaderboard-2.0 | byte-identical branches — same commit |
| 0.9.10.1 | leaderboard-1.0 | Leaderboard 1.0 only |
| 0.9.13 and older | the matching 0.9.x tag/branch | frozen, unsupported |
The minimum enforced in code is MIN_CARLA_VERSION = '0.9.14' on master, and
it is a hard ImportError at startup, not a warning. 0.10.0 passes that check
because version comparison is numeric per component (0.10 > 0.9), and 1.x
passes it on the major alone.
Step 3: Clone
# UE4 / CARLA 0.9.16
git clone -b master --single-branch https://github.com/carla-simulator/scenario_runner.git
# UE5 / CARLA 0.10.0
git clone -b ue5-master --single-branch https://github.com/carla-simulator/scenario_runner.git
# driving the Leaderboard (pick the branch that matches your leaderboard checkout)
git clone -b leaderboard-2.1 --single-branch https://github.com/carla-simulator/scenario_runner.git
--single-branch is worth it: the repo carries the OpenSCENARIO 2.0 test corpus
and, on ue5-master, ~230k lines of Scenic OpenDRIVE assets.
Already cloned? Switch instead of re-cloning:
python3 scripts/install_scenario_runner.py install --root ~/scenario_runner --branch ue5-master
Step 4: Requirements
# into the SAME interpreter that imports carla — not a fresh venv unless carla is there too
python3 -m pip install -r ~/scenario_runner/requirements.txt
py_trees==0.8.3 is pinned and not optional: the behaviour-tree API changed
in 2.x and scenarios fail with attribute errors. numpy must stay <2 for the
same reason the CARLA client does — the bindings are built against the 1.x C API.
Step 5: Environment
export SCENARIO_RUNNER_ROOT=~/scenario_runner
export CARLA_ROOT=/path/to/CARLA_0.9.16 # the extracted release or checkout
export PYTHONPATH="${SCENARIO_RUNNER_ROOT}:${CARLA_ROOT}/PythonAPI/carla:${PYTHONPATH}"
bash scripts/check_env.sh
python3 scripts/install_scenario_runner.py verify
${CARLA_ROOT}/PythonAPI/carla is required even when carla is pip-installed.
scenario_runner.py imports agents.navigation.global_route_planner at module
load, and the agents package ships only inside a CARLA tree — never in the
wheel. A pip-only setup dies with ModuleNotFoundError: No module named 'agents'
before any scenario runs. This is the single most common install failure.
SCENARIO_RUNNER_ROOT is also read at runtime by ScenarioRunner itself, to
locate srunner/scenarios/*.py and to resolve --record paths. Exporting it is
not just for the shell's benefit.
Recording the path
An export lasts until the shell exits. Persist SCENARIO_RUNNER_ROOT instead, so the
next session — and list_skills — still knows where this went:
set_config({"SCENARIO_RUNNER_ROOT": "<the checkout path>"})
Without it the group this just enabled keeps reporting available: false,
and the next skill re-detects from scratch. CARLA_ROOT is the only CARLA
path to record: set_config derives the engine-specific variable itself.
Examples
Example 1: "install scenario runner for my CARLA 0.9.16"
detect → client 0.9.16 → plan says master. Clone -b master, pip install
requirements, export the three variables, check_env.sh passes, then run
[[run-scenario]] --list.
Example 2: "I have CARLA 0.10.0 and scenarios don't work"
Almost certainly master checked out against a UE5 server. install --branch ue5-master switches it. Note the knock-on effects: 0.10.0 ships Town10HD_Opt
only and just 11 of the 101 configs were retargeted to it, the ego blueprint
is vehicle.lincoln.mkz (not mkz_2017), and weather behaviours are
commented out in basic_scenario.py. list_scenarios.py --town Town10HD_Opt
prints the runnable set.
Example 3: "set up SR to run the leaderboard"
Do it the other way round — start from [[install-leaderboard]], which detects the
leaderboard version and names the SR branch to pair with it. Installing SR first
means guessing.
Troubleshooting
Problem: ModuleNotFoundError: No module named 'agents'
Cause: carla came from a wheel; agents only exists in a CARLA tree.
Solution: set CARLA_ROOT and add ${CARLA_ROOT}/PythonAPI/carla to PYTHONPATH.
Problem: ImportError: CARLA version 0.9.14 or newer required
Cause: master against an older client. The check reads the client package
metadata, not the server.
Solution: upgrade the client ([[install-python-api]]), or check out the branch for
your version.
Problem: Scenario 'FollowLeadingVehicle_1' not supported ... Exiting
Cause: usually the wrong branch — ue5-master deleted change_lane.py,
cut_in.py, freeride.py and no_signal_junction_crossing.py. Can also be
SCENARIO_RUNNER_ROOT unset, which makes the scenario glob resolve to ./.
Solution: export SCENARIO_RUNNER_ROOT; confirm the branch with
git -C $SCENARIO_RUNNER_ROOT rev-parse --abbrev-ref HEAD.
Problem: scenario starts, then AttributeError inside py_trees
Cause: py_trees 2.x.
Solution: pip install py-trees==0.8.3.
Problem: UnicodeEncodeError: 'ascii' codec can't encode character '✓'
Cause: --debug prints py_trees tick marks to a non-UTF-8 stdout (docker, cron).
Solution: export PYTHONIOENCODING=utf-8 — scripts/env.sh does this for you.
Problem: two CARLA versions on one machine, SR picks the wrong one
Cause: PYTHONPATH order, or a stale egg earlier in the path.
Solution: one venv per CARLA version; python3 -c "import carla; print(carla.__file__)"
tells you which one actually won.
Outputs
A scenario_runner checkout on a known branch, its requirements installed in the
interpreter that has carla, and the three exports needed to run it. verify
prints the branch, the client/server versions and the scenario count it can see.
Version details — what each branch contains, what UE5 dropped, which branch the
Leaderboard needs — in references/versions.md.