uv Cheatsheet — Scripts & Tools

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///

import requests
from rich import print

resp = requests.get("https://api.github.com/repos/astral-sh/uv")
print(resp.json()["stargazers_count"])

uv run stars.py

# Create a script and inject metadata
echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
uv add --script example.py requests

# Add multiple
uv add --script example.py rich httpx

uv remove --script example.py rich

# Inside a project — runs in the project environment
uv run main.py
uv run -- pytest -v
uv run -- ruff check .

# With extra packages (not in your project deps)
uv run --with rich -- python -c "from rich import print; print('hello')"

# With a specific Python version
uv run --python 3.11 main.py

# Run a standalone script (outside any project)
uv run --no-project script.py

# Run a tool once (downloads, runs, discards)
uvx ruff check .
uvx black --check .
uvx pycowsay "hello world"

# Specify a version
uvx ruff@0.8.0 check .

# Run a tool whose command name differs from the package name
uvx --from httpie http https://api.github.com

# Run with a specific Python version
uvx --python 3.12 ruff check .

# Install globally
uv tool install ruff
uv tool install black
uv tool install mypy

# Install with extras
uv tool install 'mkdocs[material]'

# Upgrade a tool
uv tool upgrade ruff

# Upgrade all tools
uv tool upgrade --all

# List installed tools
uv tool list

# Uninstall
uv tool uninstall ruff

# Show where tools are stored
uv tool dir

# Show where tool binaries are linked
uv tool dir --bin