uv run --with PKG: add a package for one run without installing it
- tool
- uv
- command
- uv run
- flag
- --with PKG[,PKG...], --with-requirements FILE, --with-editable PATH
- default
- none (only the project or script dependencies are available)
uv run --with rich python app.py runs the command with rich available, without adding it to the project or installing it into .venv. uv builds a cached environment that layers the extra packages on top of the project's own dependencies, so it is ideal for a debugger, a profiler or a quick experiment with a library. The flag can be repeated, accepts version specifiers (--with "httpx<1"), and also works outside any project.
Without and with --with
echo "--- without --with"
uv run -q --no-project python -c "import humanize" 2>&1 | tail -1
echo "--- --with humanize==4.11.0"
uv run -q --no-project --with humanize==4.11.0 python -c "import humanize; print(humanize.intcomma(1234567))"
echo "--- two packages"
uv run -q --no-project --with humanize==4.11.0 --with six==1.16.0 python -c "import humanize, six; print(six.__version__)"Output
--- without --with ModuleNotFoundError: No module named 'humanize' --- --with humanize==4.11.0 1,234,567 --- two packages 1.16.0
The first command fails with ModuleNotFoundError because nothing provides the module. With the flag the import works; the next run with the same packages reuses the cached environment and starts almost instantly.
Options
| Option | Effect |
|---|---|
| --with PKG | Add a package (with an optional version specifier) for this run |
| --with a,b / repeated --with | Several packages |
| --with-requirements FILE | Add the packages listed in a requirements.txt or a script |
| --with-editable PATH | Add a local package in editable mode |
| --no-project | Ignore any pyproject.toml; only the --with packages are present |
| --isolated | Do not reuse the project environment; build a fresh one |
| --python 3.12 | Choose the interpreter for the run |
Inside a project
uv run --with ipython ipython # REPL with the project's dependencies plus IPython
uv run --with pytest-cov pytest --cov # a plugin only for this run
uv run --with "pandas<2" python report.py # try an older version without editing the lockIf --with asks for a version that conflicts with a locked project dependency, the layered environment wins for that run: the requested version shadows the project's. Treat it as an experiment and record a permanent change with uv add.
--with versus the alternatives
- Inline script metadata (
# /// script) stores the dependencies in the file itself, so every run of the script gets them: see uv run with inline dependencies. - uvx runs a tool from a package in its own environment, unrelated to the project: see uvx --from.
- uv add changes
pyproject.tomlanduv.lockfor everyone.
Pitfalls
- The flag must come before the command: in
uv run python --with x, the text is passed to Python. - Packages added with
--withare not inuv.lock, so CI will not have them; code that imports them must not be committed withoutuv add. uv pip installinto the project.venvis the wrong fix for a one-off need: the nextuv syncremoves the package again.
FAQ
Does uv run --with change pyproject.toml or uv.lock?
No. The extra packages are installed into a cached, temporary environment layered on top of the project environment. Nothing is written to pyproject.toml, uv.lock or .venv; use uv add for a permanent dependency.
Can I use --with outside a project?
Yes. With --no-project, or in a folder without pyproject.toml, uv run --with pkg python creates an environment that contains only the requested packages, which is handy for one-off experiments.
How do I pass many packages at once?
Repeat the flag or separate names with commas (--with a,b), or put them in a file and use --with-requirements requirements.txt.