uv sync --extra: Install Optional Extras
uv sync --extra installs the optional dependencies declared under a project extra, on top of the base set.
uv sync --extra lets a job opt into optional features like a plotting or async extra without adding them to the base install. It maps to pyproject optional-dependencies.
What it does
uv sync --extra <name> installs the packages listed under that key in [project.optional-dependencies], alongside the default dependencies. --all-extras pulls in every extra, and --no-extra excludes a specific one when combined with --all-extras.
Common usage
uv sync --extra plot
uv sync --extra plot --extra async
uv sync --all-extras
uv sync --all-extras --no-extra heavy
uv sync --all-extras --frozenOptions
| Flag | What it does |
|---|---|
| --extra <name> | Install one optional extra (repeatable) |
| --all-extras | Install every declared extra |
| --no-extra <name> | Exclude one extra when using --all-extras |
| --frozen | Install from the lock without re-locking |
| --no-install-project | Install dependencies but not the project itself |
In CI
Match the extras to the job: a docs build syncs --extra docs, a full test matrix may use --all-extras. Combine with --frozen so the install reflects the committed lock. Extras are part of the lockfile, so uv.lock must already contain them or the frozen install errors.
Common errors in CI
"error: Extra <name> is not defined in the project's optional-dependencies table" means a typo or an undefined extra; check pyproject.toml. With --frozen, requesting an extra missing from uv.lock yields "The lockfile ... needs to be updated"; run uv lock. Note extras (optional-dependencies) are distinct from dependency groups; do not pass a group name to --extra.