Python uv Command Reference

A general-purpose baseline for now — the plan is to trim this down to the commands and flags I actually use day to day, and drop the rest.

Projects

uv init

Create a new project (adds pyproject.toml, a src layout, and a .python-version).

Flag	Description
--lib	Scaffold an importable library instead of an app.
--package	Set up as a packaged project (with a build backend).
--no-readme	Skip creating a README.md.

uv add / uv remove

Add or remove a dependency, updating pyproject.toml and the lockfile.

Flag	Description
--dev	Add to the dev dependency group instead of the main one.
--optional <group>	Add as an optional dependency under <group>.
--group <name>	Add to a named dependency group.
--editable, -e	Install a local path dependency in editable mode.

uv sync

Install the project’s dependencies to match the lockfile exactly.

Flag	Description
--all-extras	Install all optional extras.
--no-dev	Skip the dev dependency group.
--frozen	Sync without updating the lockfile, even if it’s out of date.
--locked	Assert the lockfile is up to date; fail instead of updating it.

uv lock

Resolve dependencies and write/update uv.lock without installing anything.

Flag	Description
--upgrade	Upgrade all packages to the latest allowed versions.
--upgrade-package <pkg>	Upgrade a single package.
--check	Check whether the lockfile is up to date; don’t write it.

uv run

Run a command inside the project’s environment, syncing first if needed.

Flag	Description
--no-sync	Skip the automatic sync before running.
--with <pkg>	Run with an extra package available, without adding it to the project.
-- <args>	Pass the remaining arguments through to the command.

uv build

Build the project into source and wheel distributions (dist/).

uv tree

Show the resolved dependency tree.

Python versions

Command	Description
uv python list	List available and installed Python versions.
uv python install <version>	Install a specific Python version (e.g. 3.12).
uv python pin <version>	Pin the project’s Python version (.python-version).
uv python find <version>	Show the path to a matching installed interpreter.
uv python uninstall <version>	Remove an installed Python version.

Virtual environments

uv venv

Create a virtual environment (default: .venv).

Flag	Description
--python <version>	Use a specific Python version for the environment.
--seed	Install pip/setuptools/wheel into the new environment.

pip-compatible interface

uv pip is a drop-in, much faster replacement for common pip/pip-tools workflows — useful outside a uv-managed project.

Command	Description
uv pip install <pkg>	Install a package into the active/target environment.
uv pip install -r requirements.txt	Install from a requirements file.
uv pip uninstall <pkg>	Uninstall a package.
uv pip list	List installed packages.
uv pip freeze	Output installed packages in requirements format.
uv pip compile requirements.in	Resolve and pin a requirements.in into a lockfile-style output.
uv pip sync requirements.txt	Make the environment match a requirements/lock file exactly.

Tools (pipx-style)

Run or install CLI tools published on PyPI into isolated environments.

Command	Description
uvx <tool>	Run a tool once, ephemerally (shorthand for uv tool run).
uv tool install <tool>	Install a tool so its command is always on PATH.
uv tool uninstall <tool>	Remove an installed tool.
uv tool list	List installed tools.
uv tool upgrade <tool>	Upgrade an installed tool.

Scripts

Run a standalone .py file with its own inline dependencies (PEP 723).

Command	Description
uv run script.py	Run a script, installing any inline dependencies first.
uv add --script script.py <pkg>	Add a dependency to a script’s inline metadata.
uv run --with <pkg> script.py	Run a script with an extra package available.

Housekeeping

Command	Description
uv self update	Update uv itself to the latest release.
uv cache clean	Clear uv’s package/build cache.
uv cache dir	Show the path to uv’s cache directory.