Install Scenic
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.
Scenic is pure Python — there is nothing to build and pip install scenic is
the whole install. Two things make it go wrong anyway, and neither reports an
install error:
- The
scenic CLI and the carla client must be in ONE interpreter. Scenic
loads the client itself when a scenario names the CARLA model. Split them and
the failure arrives mid-run as a model import error, not at install time.
- Scenic's blueprint tables are keyed on the CARLA client version. With no
table for that version, every vehicle and prop category resolves empty and
every scenario fails at sample time with "no blueprints recorded".
So the install order is client first, Scenic second, into the same
interpreter. install_scenic.py refuses to install into an interpreter with no
client unless you pass --force.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh)
- [ ] Step 2: Pick the interpreter — the one that has the CARLA client
- [ ] Step 3: See the plan for this machine
- [ ] Step 4: Install (and clone examples if they are wanted)
- [ ] Step 5: Verify, and record `SCENIC_ROOT` and `PYTHON` with `set_config`
Step 1-3: What is here, and what to do about it
PYTHON=/path/to/venv/bin/python bash scripts/check_env.sh
python3 scripts/install_scenic.py detect # interpreter, Scenic, client, tables
python3 scripts/install_scenic.py plan # the exact commands, and why
Every subcommand takes --python to act on another interpreter:
python3 scripts/install_scenic.py --python ~/.venvs/carla/bin/python detect
detect is the one to read first. It prints which CARLA versions the installed
Scenic has blueprint tables for, and flags a CLI that belongs to a different
environment than the interpreter — the pyenv-shim trap, which otherwise surfaces
much later as a confusing model import failure.
Step 4: Install
# into the interpreter that has the client
python3 scripts/install_scenic.py install
# a specific version
python3 scripts/install_scenic.py install --version 3.1.1
# also clone upstream for the example scenarios and map assets
python3 scripts/install_scenic.py install --clone ~/Scenic
The wheel ships world models only — no example scenarios and no map assets.
--clone is how you get examples/ and assets/maps/CARLA/*.xodr. Skip it if
you are running a ScenarioRunner checkout's own scenarios, which carry their own
copies under srunner/scenic/.
install runs verify when it finishes.
Step 5: Verify and export
python3 scripts/install_scenic.py verify
Checks the five things that actually matter, and exits non-zero on any:
| Check | Why it matters |
|---|
scenic importable | the install worked |
| CLI belongs to this interpreter | otherwise a run uses a different Scenic |
carla client present | Scenic loads it for the CARLA model |
carla is the extension, not a directory | a directory named carla on sys.path imports as an empty namespace package |
| blueprint table for this client version | otherwise every category is empty |
scenic.simulators.carla.simulator imports | the real binding between Scenic and the client |
Then export the root, which is what the scenic skill group is gated on:
export SCENIC_ROOT=~/Scenic # a checkout, for examples
# or, for a pip-only install, the installed package directory:
export SCENIC_ROOT=$(python3 -c 'import os,scenic;print(os.path.dirname(scenic.__file__))')
Running and authoring scenarios is out of scope here — see
[[run-scenic-scenario]] and [[create-scenic-scenario]].
Recording the path
An export lasts until the shell exits. Persist SCENIC_ROOT and PYTHON instead, so the
next session — and list_skills — still knows where this went:
set_config({"SCENIC_ROOT": "<the checkout or package dir>",
"PYTHON": "<the interpreter Scenic went into>"})
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 Scenic so I can run .scenic files"
install_scenic.py detect to find the interpreter holding the client, then
install --python <that> --clone ~/Scenic, then verify. Export SCENIC_ROOT
and the scenic skills become available.
Example 2: "Scenic says there are no bicycle blueprints"
Not an install fault by itself. detect prints the table versions; if the client
version is listed, the category is empty in Scenic's data for that version even
though the build may contain such assets. Upgrading Scenic may add it; otherwise
name the id explicitly. See [[create-scenic-scenario]].
Example 3: "scenic is installed but a scenario cannot import the model"
Almost always the two halves in different environments. verify compares the
CLI's directory against the interpreter's and fails loudly on a mismatch.
Troubleshooting
Problem: refusing to install: <python> has no carla client
Cause: the guard. Installing Scenic into a client-less interpreter looks fine and
fails later.
Solution: install the client there first ([[install-python-api]]), or --force if
you genuinely want Scenic alone.
Problem: the scenic command runs a different Scenic than expected
Cause: a version manager's shim directory precedes the environment on PATH.
Solution: call the CLI by full path — <env>/bin/scenic — which is what the
scenic skills' env.sh derives from PYTHON.
Problem: no blueprint table for client X
Cause: the installed Scenic predates that CARLA release.
Solution: install without --version to take the newest; plan prints the
available versions. If none has a table for that client, Scenic does not support
it yet.
Problem: no example scenarios after installing
Cause: expected — the wheel excludes examples/, and the sdist does too.
Solution: install --clone <dir>, or use a ScenarioRunner checkout's
srunner/scenic/.
Problem: pip install scenic pulls a numpy that breaks the client
Cause: Scenic's dependency set is wide (numpy, scipy, shapely, trimesh,
matplotlib, opencv).
Solution: install into a dedicated virtualenv alongside the client rather than a
shared one, so a resolver change cannot disturb other work.
Outputs
Scenic installed into a named interpreter, verify reporting PASS on all checks,
and SCENIC_ROOT exported so the scenic skill group reports available.
Optionally an upstream checkout providing examples/ and assets/maps/.
Version-keying, the examples question and the interpreter rule are covered in
references/compatibility.md.