uv

uv 0.4+

Quick reference for the uv CLI: Python project init, dependency management, virtual environments, lockfile resolution, tool runners, and self-update — with common options and practical examples.

39 commands

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

The official one-line installer for macOS / Linux — installs uv to `~/.local/bin` and adds it to the PATH for the current shell.

curl -LsSf https://astral.sh/uv/install.sh | sh

pipx install uv

Install uv as an isolated CLI tool via pipx (recommended on managed Python installs).

pipx install uv

winget install --id=astral-sh.uv

Install uv via Windows Package Manager (Windows 10/11).

winget install --id=astral-sh.uv

Self-update

uv self update

Update uv to the latest release. Use `--preview` to grab the next pre-release.

--preview; --stable

uv self update

Python versions

uv python install <ver>

Download a Python interpreter into uv's managed cache (`~/.cache/uv` / `%LOCALAPPDATA%\uv`). Pass `3.12`, `3.11.9`, or even `cpython-3.13.0a5` for nightly.

3.12; 3.11.9; [email protected]; --mirror

uv python install 3.12

uv python list

List every Python interpreter uv can download (CPython, PyPy, free-threaded builds). Use `--only-installed` to filter to ones you've already got.

--only-installed; --all-versions; --arch; --os

uv python list --only-installed

uv python find

Print the path to the interpreter uv would use for the current directory. Respects `.python-version`, `pyproject.toml`, and the active virtualenv.

uv python find 3.12

uv python pin <ver>

Pin a Python version for the current project — writes `.python-version`. CI / Docker can read this to match the local interpreter.

uv python pin 3.12

Project init

uv init <name>

Scaffold a new Python project: `pyproject.toml`, hello-world module, `.gitignore`, optional tests / README.

--package build as a distributable package; --lib build as a library; --bare no source layout; --python <ver>; --no-readme; --no-pin-python

uv init my-app --package --python 3.12

uv init --lib <name>

Initialize a library project (src layout, exposes `from <name> import ...`).

uv init my-lib --lib

Sync

uv sync

Install every dependency declared in `pyproject.toml` and `uv.lock` into the project virtualenv. Idempotent; `--frozen` skips lockfile updates, `--locked` fails if it would change.

--frozen; --locked; --no-dev; --extra <name>; --all-extras; --group <name>; --no-install-project

uv sync --all-extras

uv lock

Resolve and write the `uv.lock` file without installing. Use `--check` to verify it matches `pyproject.toml` (handy in CI).

--check; --upgrade; --upgrade-package <pkg>; --frozen; --dry-run

uv lock --check

Add / Remove

uv add <pkg>

Add a dependency to `pyproject.toml`, update `uv.lock`, and install into the venv.

--dev; --group <name>; --optional <extra>; --upgrade; --<specifier>; --editable <path>; --raw; --no-sync; --python <ver>

uv add requests rich

uv add 'requests>=2.32'

Add a dependency with a version specifier (PEP 440). Quotes recommended for the shell.

uv add 'requests>=2.32,<3'

uv add --dev pytest ruff mypy

Add dev-only dependencies — go under `[dependency-groups].dev]` in `pyproject.toml`.

uv add --dev pytest ruff

uv add --group docs sphinx

Add to a named dependency group. Multiple groups can be installed via `uv sync --group docs --group lint`.

uv add --group lint ruff mypy

uv remove <pkg>

Remove a dependency from `pyproject.toml`, the lockfile, and the venv.

--dev; --group <name>; --optional <extra>

uv remove requests

Run

uv run <cmd>

Run a command inside the project's virtualenv. Re-creates the venv automatically if it's missing.

--with <pkg> add ephemeral dep; --with-requirements <file>; --no-sync; --locked; --frozen; --isolated; --refresh-package <pkg>; --package <name>

uv run python -m myapp

uv run pytest

Run a tool installed in the project venv — no need to source the venv first.

uv run pytest -x --cov

uv run --with requests python -c 'print(requests.__version__)'

Execute an ephemeral script with a one-off dependency that gets cached for next time.

uv run --with httpx python -c 'import httpx; print(httpx.get("https://example.com").status_code)'

uv run script.py

Run a Python script that uses PEP 723 inline metadata (uv reads `# /// script` blocks at the top and resolves them on the fly).

--no-sync

uv run ./hello.py

Manage venv

uv venv

Create a project virtualenv at `.venv`. Use `--seed` to bundle pip + setuptools.

<path>; --python <ver>; --seed; --no-seed; --prompt <name>; --system-site-packages; --clear; --relocatable

uv venv --python 3.12

uv venv --seed

Create the venv and also install pip / setuptools / wheel — needed by `pip install` workflows inside the venv.

uv venv --seed --python 3.11

uv remove

Delete the project venv and lockfile. Pair with `uv sync` to start fresh.

uv remove && uv sync

Run a CLI tool

uvx <tool>

Run a CLI tool in an ephemeral environment (alias for `uv tool run`). The tool is cached after first use.

<tool>@<ver>; --from <pkg>; --with <dep>; --upgrade; --quiet

uvx ruff check .

uvx --from 'pycowsay>=2.0' cowsay 'Hello uv!'

Run a tool exposed by a specific package (when the package name and CLI name differ).

uvx --from 'sqlfluff' sqlfluff lint models/

Install tools

uv tool install <pkg>

Install a global CLI tool into an isolated environment (analogous to pipx). The tool becomes available on PATH.

--python <ver>; --with <dep>; --reinstall; --quiet; --force

uv tool install ruff

uv tool list

List every CLI tool installed by `uv tool install`.

uv tool list

uv tool uninstall <pkg>

Uninstall a CLI tool installed via `uv tool install`.

--quiet

uv tool uninstall ruff

uv tool upgrade

Upgrade every installed tool to its latest version (respects `uv tool update-self` and pin files). Pass a name to target one tool.

<tool>; --all; --reinstall; --quiet

uv tool upgrade --all

Index / cache

uv cache clean

Clear uv's module cache (`~/.cache/uv`). Pair with `uv sync --refresh` to force a full re-download.

<package>; --force

uv cache clean ruff

uv cache dir

Print the cache directory uv uses for downloaded wheels.

uv cache dir

uv pip install <pkg>

Drop into pip-compatible mode — useful when migrating an existing project or when a tool still invokes `pip`.

<pkg>; -r <requirements.txt>; -e <path>; --index-url <url>

uv pip install -r requirements.txt

uv pip compile <in> -o <out>

Resolve a `requirements.in` to a pinned `requirements.txt` (analogous to `pip-tools`).

uv pip compile requirements.in -o requirements.txt --upgrade

Build / Publish

uv build

Build source distribution and wheel for the project (uses hatchling / setuptools / poetry core plugins depending on `pyproject.toml`).

-o <dir>; --wheel; --sdist; --no-byte-compile

uv build

uv publish

Upload built artifacts to PyPI (or a custom index via `--index`).

--token <pypi-token>; --index <name>; --publish-url <url>; --trusted-publishing <on|off>

uv publish --token $PYPI_TOKEN

Diagnose

uv --version

Print uv's version.

uv --version

uv help

List every uv subcommand.

uv help

uv help <subcommand>

Print the full flag list for one subcommand.

uv help sync

Related command cheatsheets

Python Development

conda

Quick reference for Conda CLI commands: environment management, package install / search, channels, lockfiles, configuration, and cleanup — with common options and practical examples.

40 commands

Conda 24+

Python Development

pip

Quick reference for the pip package installer CLI: install / uninstall / inspect packages, virtual environments, requirements files, configuration, and index management — with common options and practical examples.

37 commands

pip 24+

Python Development

pytest

Quick reference for the pytest CLI: test discovery, selection, fixtures, markers, parallelism, parametrize, and coverage integration — with common options and practical examples.

34 commands

pytest 8+

Trademark & Use Notice

These command-line tool cheatsheets are open community references. The names, logos, and trademarks of the tools referenced here (such as Git™, Docker™, Kubernetes®, kubectl, PostgreSQL®, MySQL®, Redis™, MongoDB®, Linux™, PowerShell™, Vim™, and others) are the property of their respective owners and are used here solely for identification and reference purposes.

All content in these cheatsheets is independently authored as a simplified, self-contained reference. It is not affiliated with, endorsed by, or sourced from any official documentation. Command listings, flag descriptions, and examples are original simplifications; for authoritative information please consult the official documentation of each tool.

Command syntax and option flags may differ across tool versions. The version tags shown reflect stable releases; behavior may differ in other versions. This cheatsheet does not imply any preference or recommendation by the trademark holders.

If a trademark or copyright owner believes that any content on this site infringes their rights, please send an email to [email protected]. Upon receiving valid proof of rights, we will modify or remove the relevant content within a reasonable period.

This website assumes no legal liability for any direct or indirect losses arising from the use of information presented on these pages.

About uv

uv is an extremely fast Python package and project manager written in Rust by Astral (the team behind ruff and the Python type checker ty). First released in 2024, uv aims to replace pip, pip-tools, pipx, pyenv, virtualenv, and parts of Poetry / pdm — all from one binary. It installs packages 10-100× faster than pip because it parallelises downloads and uses a global module cache (`~/.cache/uv`). uv speaks the standard `pyproject.toml` (PEP 621) and the newer PEP 723 inline-script metadata (single-file scripts with their own declared deps). It works on macOS, Linux, Windows and ships as a single ~30 MB binary (homebrew / pipx-installer / curl-install.sh / winget). uv never uploads your code anywhere — it only talks to the configured Python package index (`--index-url`, defaults to PyPI).

Cheatsheet version 1.0.0