TerminalSkills/skills

uv — Fast Python package and project manager

Overview

uv is a single binary from Astral that covers the whole Python workflow: projects with a cross-platform lockfile (uv.lock), single-file scripts with inline dependencies, command-line tools (uvx), Python interpreter installs, and a drop-in uv pip interface. It downloads Python itself when needed, so a machine needs nothing but uv.

Instructions

Installation

# Package managers
pipx install uv
brew install uv
winget install --id=astral-sh.uv -e

Astral also publishes a standalone installer for machines without a package manager; the installation page at https://docs.astral.sh/uv/getting-started/installation/ has the current command and checksums.

uv --version
uv self update     # standalone installer only; otherwise upgrade with the package manager

To pin a release, put the version in the installer URL: https://astral.sh/uv/0.12.21/install.sh.

Create a project

uv init dispatch-api               # packaged app: src/dispatch_api/, uv_build backend, console script
uv init --no-package cron-jobs     # flat layout with main.py and no build system
uv init --lib geo-utils            # library with a py.typed marker
uv init --bare --python 3.12       # only pyproject.toml, in the current directory

uv init also writes .python-version, README.md, .gitignore and initialises git. --bare writes nothing but pyproject.toml, which makes it the right choice inside an existing repository.

Manage dependencies

uv add 'httpx>=0.27' 'pydantic>=2.7,<3'     # runtime dependencies
uv add --dev pytest ruff                    # dev group, not shipped to production
uv add --group docs mkdocs                  # any named dependency group
uv add --optional postgres 'psycopg[binary]'   # extra: pip install dispatch-api[postgres]
uv add -r requirements.txt                  # import an existing requirements file
uv remove httpx

uv lock --upgrade-package pydantic          # bump one package within its constraints
uv lock --upgrade                           # bump everything
uv tree --outdated --depth 1                # what has a newer release

The first uv add creates .venv/ and uv.lock. Every change updates pyproject.toml, the lockfile and the environment together.

Run and sync

uv run pytest                        # locks and syncs if needed, then runs inside .venv
uv run python -m dispatch_api
uv run --with rich python -c "import rich"   # one extra package for this command only

uv sync                              # install everything, dev group included
uv sync --locked                     # CI: fail if uv.lock does not match pyproject.toml
uv sync --frozen --no-dev            # production: use uv.lock as-is, skip the dev group
uv sync --extra postgres
uv lock --check                      # exit non-zero when the lockfile is stale

No activation is needed; uv run finds the project environment by itself.

Scripts with inline dependencies

uv init --script fetch-rates.py --python 3.12
uv add --script fetch-rates.py 'httpx<1' rich
uv run fetch-rates.py
uv lock --script fetch-rates.py      # writes fetch-rates.py.lock for reproducible runs

uv add --script maintains a metadata block at the top of the file:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "httpx<1",
#     "rich>=15.0.0",
# ]
# ///

Add #!/usr/bin/env -S uv run --script as the first line and chmod +x the file to run it directly.

Tools

uvx ruff check .                         # run without installing; uvx = uv tool run
uvx [email protected] check .                  # exact version
uvx --from 'markitdown[pdf]' markitdown q3-board-report.pdf   # command name differs from the spec
uv tool install ruff                     # permanent, isolated install on PATH
uv tool upgrade --all
uv tool list
uv tool uninstall ruff

Installed tools land in the directory printed by uv tool dir --bin; uv warns when that directory is not on PATH.

Python versions

uv python install 3.12 3.13
uv python list --only-installed
uv python pin 3.12              # writes .python-version
uv run --python 3.13 pytest     # one-off run on another interpreter
uv python upgrade 3.12          # latest patch release of 3.12
uv venv --python 3.12           # plain virtual environment at .venv

Requests accept 3.12, 3.12.3, >=3.11,<3.13, [email protected] and 3.13t (free-threaded). uv downloads a missing interpreter automatically; pass --no-python-downloads to forbid that.

pip-compatible interface

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt --universal
uv pip sync requirements.txt        # removes anything not listed
uv pip install --python .venv/bin/python 'rich>=13'

CI and Docker

name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.12.21"
          enable-cache: true
      - run: uv python install
      - run: uv sync --locked --all-extras --dev
      - run: uv run pytest

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.12.21 /uv /uvx /bin/
WORKDIR /app
ENV UV_NO_DEV=1 UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

# Dependencies first, so this layer is reused until uv.lock changes
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "dispatch_api"]

Add .venv to .dockerignore; a host environment does not work inside the image.

Examples

Example 1: Move a requirements.txt service to a locked uv project

Request: "Our dispatch-api repo has requirements.txt and requirements-dev.txt. Move it to uv with a lockfile and make the tests run."

cd dispatch-api
uv init --bare --python 3.12
uv python pin 3.12
uv add -r requirements.txt
sed '/^-r /d' requirements-dev.txt | uv add --dev -r -
uv run python -m pytest -q
uv run ruff check .

Result: pyproject.toml lists the five runtime packages and a dev group, uv.lock pins 30 packages, and the checks pass. Abridged output:

Initialized project `dispatch-api`
Pinned `.python-version` to `3.12`
 + uvicorn==0.34.0
 + pytest==8.3.4
 + ruff==0.8.6
1 passed, 1 warning in 0.12s
All checks passed!

Example 2: A self-contained script

Request: "Write a disk usage report script I can copy to any server and run without setting up an environment."

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["rich>=13"]
# ///
import shutil

from rich.console import Console
from rich.table import Table

usage = shutil.disk_usage("/")
table = Table(title="Disk usage")
table.add_column("Total GB")
table.add_column("Free GB")
table.add_row(f"{usage.total / 1e9:.0f}", f"{usage.free / 1e9:.0f}")
Console().print(table)

chmod +x disk-report.py
./disk-report.py

Result: uv builds a cached environment with rich on the first run and prints the table; later runs start immediately.

      Disk usage
┏━━━━━━━━━━┳━━━━━━━━━┓
┃ Total GB ┃ Free GB ┃
┡━━━━━━━━━━╇━━━━━━━━━┩
│ 3936     │ 2211    │
└──────────┴─────────┘

Guidelines

• Commit uv.lock and .python-version. Never edit uv.lock by hand; change pyproject.toml or use uv add, uv remove and uv lock.
• --locked or --frozen: --locked verifies the lockfile and fails when it is stale, which suits CI. --frozen skips the check and installs exactly what the file says.
• uv sync is exact, uv run is not. uv sync removes packages that are not in the lockfile, including anything added with uv pip install. uv run only adds what is missing.
• uv pip picks its target by discovery: the active VIRTUAL_ENV, then .venv in the current directory or the nearest parent. Run from the wrong folder and it installs into someone else's environment. In scripts pass --python with the environment path.
• Flat projects and pytest: with --bare or --no-package the project itself is not installed, so uv run pytest can fail with ModuleNotFoundError. Use uv run python -m pytest, or set pythonpath = ["."] under [tool.pytest.ini_options].
• uv init defaults to a packaged src/ layout. Pass --no-package for a script-style project with main.py.
• Experimental commands: uv format, uv check and uv audit print a warning that they may change. Do not build pipelines on them yet.
• Private indexes: declare them under [[tool.uv.index]] and pass credentials through environment variables named after the index: for an index called internal, UV_INDEX_INTERNAL_USERNAME and UV_INDEX_INTERNAL_PASSWORD. Never commit them. The default first-index strategy protects against dependency confusion; avoid unsafe-best-match.
• Supply chain: uv run, uvx and scripts with inline metadata download and execute packages. Review the dependency list of any script from an untrusted source before running it.
• uv self update works only for installs made with the standalone installer.
• CI cache: run uv cache prune --ci before saving the cache to keep it small.
• When NOT to use it: uv installs from Python package indexes, git and local paths. It does not install conda packages or system libraries, so keep conda for stacks that depend on them.