uv Expert

Upgrading

uv self update

Core Concepts

uv replaces multiple tools: pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv.

Key Commands Overview

Common Workflows

Running Scripts

Basic execution:

uv run script.py

With dependencies:

uv run --with requests script.py
uv run --with 'rich>12,<13' script.py

With inline metadata (recommended for recurring use):

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

import requests
from rich.pretty import pprint

Add dependencies with: uv add --script script.py 'requests<3' 'rich'

Executable scripts with shebang:

#!/usr/bin/env -S uv run --script

print("Hello, world!")

Working with Projects

Create a new project:

uv init my-project
cd my-project

This creates: pyproject.toml, .python-version, README.md, main.py, .gitignore

Add dependencies:

uv add requests
uv add 'requests==2.31.0'
uv add git+https://github.com/psf/requests
uv add -r requirements.txt -c constraints.txt

Remove dependencies:

uv remove requests

Sync environment:

uv sync          # Install all dependencies
uv lock          # Update lockfile only
uv lock --upgrade-package requests  # Upgrade specific package

Run commands:

uv run python script.py
uv run -- flask run -p 3000

Build and publish:

uv build
uv publish

Using Tools (uvx)

uvx runs tools in temporary environments without installation:

uvx ruff .                    # Run ruff
uvx [email protected] check          # Specific version
uvx --from httpie http        # Different package name
uvx --with mkdocs-material mkdocs build

Install tools permanently:

uv tool install ruff
uv tool list
uv tool upgrade ruff
uv tool uninstall ruff

Managing Python Versions

uv python install 3.12
uv python list
uv python find
uv python pin 3.11
uv python uninstall 3.10

Request specific version:

uv run --python 3.10 script.py
uvx --python 3.11 ruff

pip Interface

uv venv                          # Create virtual environment
uv pip install requests           # Install package
uv pip sync requirements.txt      # Sync from lockfile
uv pip list                       # List packages
uv pip freeze                     # Export requirements
uv pip uninstall requests        # Remove package
uv pip compile requirements.in    # Create lockfile

Cache Management

uv cache clean
uv cache prune
uv cache dir

Advanced Features

Configuration

uv supports configuration in:

• pyproject.toml under [tool.uv]
• uv.toml in project root or user config directory

Common settings:

[tool.uv]
index = ["https://pypi.org/simple"]

Authentication

uv auth login <service>
uv auth logout <service>
uv auth token <service>

Workspaces

For monorepos, create a workspace in pyproject.toml:

[tool.uv.workspace]
members = ["packages/*"]

Cross-platform builds

uv run --python-platform windows script.py
uv run --python-platform linux script.py

Reference

For detailed CLI options, refer to uv help <command> or visit https://docs.astral.sh/uv/reference/cli/

Tips

1. Use uv run instead of activating venvs - it automatically handles environment setup
2. Prefer projects over raw scripts - better dependency management
3. Use uvx for one-off tools - no installation needed
4. Lock your dependencies - always commit uv.lock for reproducibility
5. Let uv manage Python - use uv python install for version management

Looking Up Current Information

This skill has built-in knowledge of uv, but the documentation may change over time. If you need to verify the latest syntax, check for new features, or find specific details:

Start here for an overview of all available docs:

• https://docs.astral.sh/uv/llms.txt

This index lists all available documentation pages. From there you can find links to:

• Getting started guides
• CLI reference
• Concept documentation
• Integration guides (Docker, GitHub Actions, AWS, etc.)

Common reference pages:

• CLI commands: https://docs.astral.sh/uv/reference/cli/index.md
• Projects guide: https://docs.astral.sh/uv/guides/projects/index.md
• Scripts guide: https://docs.astral.sh/uv/guides/scripts/index.md
• Tools guide: https://docs.astral.sh/uv/guides/tools/index.md
• Installation: https://docs.astral.sh/uv/getting-started/installation/index.md

How to look up:

1. First, fetch https://docs.astral.sh/uv/llms.txt to see available topics
2. Find the relevant page from the index
3. Fetch that specific page for detailed, up-to-date information

Use the webfetch tool to retrieve documentation. This is especially important for:

• New features not yet in your training data
• Specific CLI option details
• Edge cases or less common use cases
• Recent changes to command syntax