This Claude skill integrates 'uv', an extremely fast Python package manager and project tool written in Rust. It streamlines the entire Python development lifecycle—from initializing projects and managing dependencies to configuring complex monorepo workspaces and managing multiple Python versions—significantly boosting developer productivity and ensuring environment reproducibility.

When should I use uv?

uv is useful in the following scenarios: • Project Lifecycle Management: Use uv to initialize new projects, manage pyproject.toml files, and handle dependencies with a lightning-fast resolver. • Monorepo & Workspace Orchestration: Organize large-scale codebases into workspaces with shared dependencies and a unified lockfile for consistent builds. • Zero-Config Script Execution: Run standalone Python scripts using PEP 723 metadata, allowing uv to automatically manage transient dependencies without manual environment setup. • Environment & Version Control: Install and switch between multiple Python versions and manage global CLI tools, effectively replacing tools like pip, pipx, and pyenv. • CI/CD Optimization: Utilize uv in automated pipelines for faster dependency installation, reproducible syncs, and optimized Docker layer caching.

name	uv
description	Python package manager and project tooling using uv. Use when working with Python projects, managing dependencies, creating virtual environments, running Python scripts, configuring workspaces/monorepos, or troubleshooting uv issues. Triggers on pyproject.toml projects, uv commands, pip replacement workflows, Python version management, workspace configuration, or CI/CD Python setup.

uv Field Manual

Assumption: uv is already installed and available on PATH.

Sanity Check

uv --version               # verify installation; exits 0

If the command fails, halt and report to the user.

Project ("cargo-style") Flow

uv init myproj                     # create pyproject.toml + .venv
cd myproj
uv add ruff pytest httpx           # fast resolver + lock update
uv run pytest -q                   # run tests in project venv
uv lock                            # refresh uv.lock (if needed)
uv sync --locked                   # reproducible install (CI-safe)

Workspaces (Monorepo)

Workspaces organize large codebases by splitting them into multiple packages with shared dependencies and a single lockfile.

Workspace root pyproject.toml:

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["shared-lib", "requests"]

[tool.uv.sources]
shared-lib = { workspace = true }    # resolve from workspace

[tool.uv.workspace]
members = ["packages/*"]             # glob patterns supported
exclude = ["packages/experimental"]  # optional exclusions

Workspace member (packages/shared-lib/pyproject.toml):

[project]
name = "shared-lib"
version = "0.1.0"
dependencies = ["pydantic"]

Key commands:

uv init mylib --package             # add new member to existing workspace
uv lock                             # locks entire workspace
uv sync                             # syncs workspace root by default
uv run --package shared-lib pytest  # run in specific member
uv sync --all-packages              # sync all members into .venv
uv sync --no-install-workspace      # deps only (good for Docker layers)

Behaviors:

uv lock operates on entire workspace
uv run/uv sync default to workspace root; use --package for members
Root tool.uv.sources apply to all members unless overridden
Member dependencies are always editable

Script-Centric Flow (PEP 723)

uv run hello.py                    # zero-dep script, auto-env
uv add --script hello.py rich      # embeds dep metadata
uv run --with rich hello.py        # transient deps, no state

CLI Tools (pipx Replacement)

uvx ruff check .                   # ephemeral run
uv tool install ruff               # user-wide persistent install
uv tool list                       # audit installed CLIs
uv tool update --all               # keep them fresh

Python Version Management

uv python install 3.10 3.11 3.12
uv python pin 3.12                 # writes .python-version
uv run --python 3.10 script.py

Legacy Pip Interface

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip sync -r requirements.txt    # deterministic install

Performance Tuning

Env Var	Purpose	Typical Value
`UV_CONCURRENT_DOWNLOADS`	saturate fat pipes	`16` or `32`
`UV_CONCURRENT_INSTALLS`	parallel wheel installs	`CPU_CORES`
`UV_OFFLINE`	enforce cache-only mode	`1`
`UV_INDEX_URL`	internal mirror	`https://…`
`UV_PYTHON`	pin interpreter in CI	`3.11`

uv cache dir && uv cache info      # show path + stats
uv cache clean                     # wipe wheels & sources

Migration Matrix

Legacy Tool	uv Replacement
`python -m venv`	`uv venv`
`pip install`	`uv pip install`
`pip-tools compile`	`uv lock`
`pipx run`	`uvx` / `uv tool run`
`poetry add`	`uv add`
`pyenv install`	`uv python install`

Troubleshooting

Symptom	Resolution
`Python X.Y not found`	`uv python install X.Y` or set `UV_PYTHON`
Proxy throttling downloads	`UV_HTTP_TIMEOUT=120 UV_INDEX_URL=https://mirror.local/simple`
C-extension build errors	`unset UV_NO_BUILD_ISOLATION`
Need fresh env	`uv cache clean && rm -rf .venv && uv sync`
Still stuck?	`RUST_LOG=debug uv ...` and open a GitHub issue

uv

When & Why to Use This Skill

Use Cases