Uv
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.From its SKILL.md
npx -y skills add stickystyle/claude-skills --skill uvAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.9 KB, as published. Nobody here has run it
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 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-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 |