Skill v1.0.1
currentAutomated scan100/1003 files
version: "1.0.1" 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 + .venvcd myprojuv add ruff pytest httpx # fast resolver + lock updateuv run pytest -q # run tests in project venvuv 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 supportedexclude = ["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 workspaceuv lock # locks entire workspaceuv sync # syncs workspace root by defaultuv run --package shared-lib pytest # run in specific memberuv sync --all-packages # sync all members into .venvuv sync --no-install-workspace # deps only (good for Docker layers)
Behaviors:
uv lockoperates on entire workspaceuv run/uv syncdefault to workspace root; use--packagefor members- Root
tool.uv.sourcesapply to all members unless overridden - Member dependencies are always editable
Script-Centric Flow (PEP 723)
uv run hello.py # zero-dep script, auto-envuv add --script hello.py rich # embeds dep metadatauv run --with rich hello.py # transient deps, no state
CLI Tools (pipx Replacement)
uvx ruff check . # ephemeral runuv tool install ruff # user-wide persistent installuv tool list # audit installed CLIsuv tool update --all # keep them fresh
Python Version Management
uv python install 3.10 3.11 3.12uv python pin 3.12 # writes .python-versionuv run --python 3.10 script.py
Legacy Pip Interface
uv venv .venvsource .venv/bin/activateuv pip install -r requirements.txtuv 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 + statsuv 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 |