uv run --with: Run With Extra Dependencies
uv run --with runs a command with extra packages layered in temporarily, without adding them to pyproject.toml.
uv run --with is handy for one-off needs: run a script that needs an extra library this once, without committing it as a project dependency.
What it does
uv run --with <pkg> resolves the project environment plus the named extra packages into an ephemeral overlay, then runs the command in it. The project manifest and lockfile are untouched; the extras exist only for that invocation.
Common usage
uv run --with rich python script.py
uv run --with "httpx>=0.27" python -c "import httpx; print(httpx.__version__)"
uv run --no-project --with cowsay cowsay hi
uv run --isolated --with pytest pytest -qOptions
| Flag | What it does |
|---|---|
| --with <pkg> | Add a package for this run only (repeatable) |
| --with-requirements <file> | Add packages from a requirements file |
| --no-project | Ignore the surrounding project entirely |
| --isolated | Run in a fresh environment, no project state |
| --python <version> | Run on a specific interpreter |
In CI
Use --with for a quick utility step (a one-off report script) instead of polluting pyproject.toml. For repeated needs, add the package to a group instead. Cache $UV_CACHE_DIR so the overlay packages are not re-downloaded every run.
Common errors in CI
"error: No solution found when resolving dependencies" means a --with package conflicts with a project pin; relax the version or run with --no-project. "Failed to parse ... requirement" means a malformed spec inside --with. If the command itself is missing, uv reports "Failed to spawn: <cmd>" because the package providing it was not added.