Getting started
Introduction
uv is a Python package and project manager. This reference covers project setup, dependencies, Python versions, lockfiles, syncing, tools, and publishing.
- uv documentation (docs.astral.sh)
- Getting started (docs.astral.sh)
- CLI reference (docs.astral.sh)
Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
On Windows, use the PowerShell installer. uv self update upgrades uv.
See: Installation
Create a project
uv init
uv init hello
uv init --app hello
uv init --lib libby
uv init --bare
Creates pyproject.toml, .python-version, README.md and .gitignore; --bare writes only pyproject.toml.
See: Creating a project
Project version
uv version
uv version 1.2.3
uv version --bump minor
uv version --dry-run
uv version reads and updates [project].version in pyproject.toml.
See: uv version
Running code
Run a command
uv run python main.py
uv run -m pytest
uv run -U python main.py
uv run --no-sync python -V
uv run syncs the environment before launching the command.
See: uv run
One-off packages
uv run --with rich python main.py
uv run --with 'pandas>=2' -m notebook
Packages passed to --with exist for this invocation only.
See: uv run --with
Run a script
uv run script.py
uv run --script script.py
uv add --script script.py rich
--script uses PEP 723 dependencies embedded in the file.
See: Scripts
Dependencies
Add and remove
uv add rich
uv add 'rich>=14'
uv add --dev pytest
uv add --group docs mkdocs
uv remove rich
uv add updates pyproject.toml, uv.lock, and the .venv.
See: Dependencies
Groups and extras
uv add --optional pdf reportlab
uv sync --group docs
uv sync --no-dev
--dev is shorthand for --group dev; --optional adds an extra.
See: Dependency groups
Inspect dependencies
uv tree
uv tree -d 2
uv tree --invert --package markdown-it-py
uv pip list
uv tree shows resolved versions; --invert finds who needs a package.
See: uv tree
Python versions
List and install
uv python list
uv python install 3.13
uv python install 3.12 3.13
uv python list marks downloadable interpreters as <download available>.
See: Python versions
Pin a version
uv python pin 3.13
uv python pin 3.13.2
uv python pin --global 3.13
A pin writes .python-version and must satisfy the project's requires-python range.
See: Python version files
Select an interpreter
uv run -p 3.12 python main.py
uv sync -p 3.12
uv python find 3.12
-p is shorthand for --python and applies to one command; uv python find prints its path.
See: uv python find
Lockfiles
Lock and check
uv lock
uv lock --check
uv lock --dry-run
--check verifies uv.lock matches the project; --dry-run previews changes.
See: uv lock
Upgrade locked versions
uv lock -U
uv lock -P rich
uv lock --upgrade-group dev
-U upgrades all locked packages; -P upgrades one package.
See: Locking and syncing
Export a lockfile
uv export --format requirements.txt -o requirements.txt
uv export --format pylock.toml -o pylock.toml
uv export --format cyclonedx1.5 -o sbom.json
cyclonedx1.5 is experimental.
See: Exporting
Syncing
Sync the environment
uv sync
uv sync --all-groups
uv sync --python 3.12
Creates .venv, installs the project, and applies uv.lock.
See: Syncing
Sync flags
| Flag | Effect |
|---|---|
--locked | Require an up-to-date lockfile |
--frozen | Use the lockfile without checking it |
--dry-run | Report changes without applying |
--no-dev | Skip the dev group |
--group docs | Include one group |
-U | Upgrade locked packages |
See: uv sync
Tools
Run a tool
uvx ruff check .
uv tool run black .
uvx --from httpie http GET example.com
uvx is shorthand for uv tool run; tools run in isolated environments.
See: Using tools
Install and manage tools
uv tool install ruff
uv tool install --with rich httpie
uv tool upgrade ruff
uv tool list
uv tool uninstall ruff
Installed tools get their own environment and executables on PATH.
See: Tools
Build and publish
Build distributions
uv build
uv build --sdist
uv build --wheel
uv build -o dist
Writes a source distribution and wheel into dist/.
See: Building packages
Publish
uv publish --token "$UV_PUBLISH_TOKEN"
uv publish --trusted-publishing always
uv publish --dry-run
Trusted publishing or $UV_PUBLISH_TOKEN keeps a literal token out of the command.
See: Publishing packages
0 Comments for this cheatsheet. Write yours!