uv Field Manual Skill | Agent Skills

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 |

Agent Skills: uv Field Manual

Skill Files