uv sync --group: Dev and Named Dependency Groups
uv sync installs dependency groups via --group, --dev, and --no-dev, letting each job pick exactly the groups it needs.
Dependency groups (PEP 735) split dev, docs, and test requirements from the base set. uv sync flags choose which groups install in a given job.
What it does
uv sync installs the default groups plus any you request. --dev includes the dev group (on by default for local work), --no-dev excludes it, --group adds a named group, and --only-group installs that group alone without the base dependencies.
Common usage
uv sync --no-dev
uv sync --group docs
uv sync --group test --group docs
uv sync --only-group lint
uv sync --no-dev --frozenOptions
| Flag | What it does |
|---|---|
| --dev / --no-dev | Include or exclude the dev group |
| --group <name> | Install an additional named group |
| --only-group <name> | Install only that group, not the base deps |
| --all-groups | Install every defined dependency group |
| --frozen | Install from the lock without re-locking |
In CI
A production image syncs --no-dev to skip test tooling; a lint job can use --only-group lint to install just the linter. Always add --frozen so the install matches the committed lockfile. Groups are recorded in uv.lock, so the lock must already include them.
Common errors in CI
"error: Group <name> is not defined in the project's dependency-groups" means a typo or undefined group. Mixing concepts is common: --group is for dependency-groups while --extra is for optional-dependencies, and swapping them errors. With --frozen, a group missing from uv.lock triggers "The lockfile ... needs to be updated".