uv add: Add a Dependency to a Project
uv add records a dependency in pyproject.toml, re-resolves the project, and writes the new versions into uv.lock.
uv add is the project-level way to bring in a package. Unlike pip install it edits pyproject.toml and the lockfile so the change is reproducible.
What it does
uv add inserts a requirement into the [project] dependencies (or a group), resolves the whole project, updates uv.lock, and installs into the project environment. It is the declarative counterpart to uv pip install.
Common usage
uv add requests
uv add "httpx>=0.27"
uv add --dev pytest ruff
uv add --optional plot matplotlib
uv add "fastapi[standard]"Options
| Flag | What it does |
|---|---|
| --dev | Add to the dev dependency group |
| --group <name> | Add to a named dependency group |
| --optional <extra> | Add as an optional dependency under an extra |
| --editable | Add a path dependency in editable mode |
| --no-sync | Update pyproject.toml and lock but do not install |
| --frozen | Add to pyproject.toml without updating the lockfile |
In CI
Pipelines rarely run uv add; it mutates pyproject.toml and uv.lock, which should be committed by a developer. If a CI step must add something, pair it with a commit step or use --frozen so the lock is not silently regenerated. Cache $UV_CACHE_DIR so resolution reuses downloaded metadata.
Common errors in CI
"error: No solution found when resolving dependencies" means the new requirement conflicts with an existing pin; read the constraint uv prints and relax it. "error: Distribution not found at: <url>" means the package name is wrong or the index lacks it. "Failed to parse: <spec>" means a malformed version specifier, e.g. a stray space inside the quotes.