uv

name: uv description: This skill should be used when working with Python projects that use uv for package and project management. Use this skill for running Python scripts and CLI tools with uv run, managing dependencies, creating projects, handling virtual environments, and executing commands within isolated project environments. Essential for projects with pyproject.toml files.

uv - Python Package and Project Manager

Contents

• Core Concept: uv run
• Quick Reference
• Common Workflows
• Dependency Management
• Python Version Management
• Scripts with Inline Dependencies
• Troubleshooting
• References

Core Concept: uv run

ALWAYS use uv run instead of bare python in uv-managed projects.

uv run automatically:

• Creates/updates the virtual environment
• Installs project dependencies
• Executes commands in isolation

# Run Python scripts
uv run script.py

# Run CLI tools
uv run pytest
uv run ruff check .

# Run Python modules
uv run python -m mymodule

Quick Reference

Essential Commands

Decision Tree

Common Workflows

1. Create New Project

uv init my-project        # Application
uv init --lib my-library  # Library
uv init                   # In current directory
uv init --python 3.12     # Specify Python version

Creates: pyproject.toml, .python-version, README.md, src/

2. Add Dependencies

uv add requests                    # Runtime
uv add 'httpx>=0.25,<0.27'        # With constraints
uv add --dev pytest pytest-cov    # Development
uv add --optional docs sphinx     # Optional group

3. Run Tests and Tools

uv run pytest
uv run pytest --cov
uv run ruff check .
uv run mypy src/

4. Update Dependencies

uv lock --upgrade               # Upgrade all
uv lock --upgrade-package numpy # Upgrade one
uv sync                         # Apply changes

5. Build and Publish

uv build                        # Build package
uv publish                      # Publish to PyPI

Dependency Management

Adding Dependencies

Temporary Dependencies

Use --with for one-off operations without modifying pyproject.toml:

uv run --with httpx python -c "import httpx"
uv run --with rich --with httpx script.py

Syncing Environment

uv sync              # Sync all
uv sync --no-dev     # Without dev deps
uv sync --all-extras # Include optional groups

Python Version Management

uv python install 3.12    # Install version
uv python list            # List available
uv python pin 3.12        # Pin for project
uv python find            # Find installations

Scripts with Inline Dependencies

Scripts can declare their own dependencies, isolated from the project:

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

import requests
import rich

Managing Script Dependencies

uv init --script analyze.py --python 3.12   # Create script
uv add --script analyze.py pandas           # Add dependency
uv run analyze.py                           # Run (uses inline deps)
uv lock --script analyze.py                 # Lock dependencies

Note: Scripts with inline metadata ignore project dependencies.

Tools Without Installation

uvx ruff check .          # Run tool ephemerally
uvx black --check .
uv tool install ruff      # Install globally
uv tool list              # List installed tools

Troubleshooting

Command Not Found After uv add

Problem: Added package with CLI, but command doesn't work.

Solution: Use uv run:

uv add ruff
uv run ruff check .  # Not just "ruff check ."

Environment Out of Sync

Problem: Dependencies changed but environment hasn't updated.

Solution:

uv sync

Wrong Python Version

Problem: Project requires different Python.

Solution:

uv python install 3.12
uv python pin 3.12

Script Ignores Project Dependencies

Problem: Script with inline metadata doesn't use project packages.

Solution: This is intentional. Either:

• Remove inline metadata to use project deps
• Add needed deps to script's inline metadata

Best Practices

1. Always use uv run - Don't manually activate venvs
2. Commit uv.lock - Ensures reproducible builds
3. Pin Python versions - Use uv python pin
4. Use --with for experiments - Test deps without modifying pyproject.toml
5. Use uvx for one-off tools - Don't pollute project deps
6. Let uv manage envs - Avoid manual pip installs

References

Project References

• CLI Reference - Complete command documentation

External Resources

• uv Documentation
• CLI Reference
• GitHub