Getting started

Introduction

uv is a Python package and project manager. This reference covers project setup, dependencies, Python versions, lockfiles, syncing, tools, and publishing.

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

FlagEffect
--lockedRequire an up-to-date lockfile
--frozenUse the lockfile without checking it
--dry-runReport changes without applying
--no-devSkip the dev group
--group docsInclude one group
-UUpgrade 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!