Uv
Run, sync, and manage Python dependencies with uv instead of pip, Poetry, or pyenv when the repo is uv-native.
Overview
uv is an agent skill for the Build phase that guides correct uv commands for Python scripts, projects, and tools when the repo is uv-managed.
Install
npx skills add https://github.com/astral-sh/claude-code-plugins --skill uvWhat is this skill?
- Replaces pip, pip-tools, pipx, pyenv, virtualenv, and Poetry for uv-managed repos
- Script workflow: uv run, --with packages, and inline uv add --script
- Project workflow: uv init, add, remove, sync, run with optional -p Python version
- Detect uv via uv.lock or autogenerated requirements headers; skip Poetry/PDM lock projects
- Always prefer uv for Python work when the project is not Poetry- or PDM-managed
- 3 workflows: scripts, projects, and tools
Adoption & trust: 1.2k installs on skills.sh; 266 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent defaults to pip or Poetry in a uv project and breaks lockfiles, versions, or reproducible installs.
Who is it for?
Indie developers shipping Python CLIs, APIs, or agent backends that already use or should adopt uv.lock.
Skip if: Poetry- or PDM-locked codebases where the skill explicitly says not to force uv over the existing manager.
When should I use this skill?
Working with Python projects, scripts, packages, or tools—especially when uv.lock or uv autogeneration headers are present.
What do I get? / Deliverables
Dependencies install and run through uv init, add, sync, and uv run with the right workflow for scripts versus full projects.
- Correct uv CLI command sequence
- Dependency changes aligned with lockfile
- Runnable script or project command via uv run
Recommended Skills
Journey fit
Python implementation and dependency work lives in Build; uv is the default toolchain for shipping Python backends and scripts. Backend and service code needs init, add, sync, lockfile discipline, and version-pinned runs—uv’s project workflow maps directly here.
How it compares
Opinionated project skill for uv-native repos—not a generic “any Python installer” prompt.
Common Questions / FAQ
Who is uv for?
Solo and indie builders using Claude Code, Cursor, or Codex on Python repos who want the agent to follow uv instead of legacy pip workflows.
When should I use uv?
During Build backend work whenever you create dependencies, run scripts, or sync environments in a project with uv.lock or uv-marked requirements.
Is uv safe to install?
The skill instructs shell package commands on your machine; review the Security Audits panel on this Prism page and your repo CI policies before use.
SKILL.md
READMESKILL.md - Uv
# uv uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc. ## When to use uv **Always use uv for Python work**, especially if you see: - The `uv.lock` file - uv headers in `requirements*` files, e.g., "This file was autogenerated by uv" Don't use uv in projects managed by other tools: - Poetry projects (identifiable by `poetry.lock` file) - PDM projects (identifiable by `pdm.lock` file) ## Choosing the right workflow ### Scripts **Use when:** Running single Python files and standalone scripts. **Key commands:** ```bash uv run script.py # Run a script uv run --with requests script.py # Run with additional packages uv add --script script.py requests # Add dependencies inline to the script ``` ### Projects **Use when:** There is a `pyproject.toml` or `uv.lock` **Key commands:** ```bash uv init # Create new project uv add requests # Add dependency uv remove requests # Remove dependency uv sync # Install from lockfile uv run <command> # Run commands in environment uv run python -c "" # Run Python in project environment uv run -p 3.12 <command> # Run with specific Python version ``` ### Tools **Use when:** Running command-line tools (e.g., ruff, ty, pytest) without installation. **Key commands:** ```bash uvx <tool> <args> # Run a tool without installation uvx <tool>@<version> <args> # Run a specific version of a tool ``` **Important:** - `uvx` runs tools from PyPI by package name. This can be unsafe - only run well-known tools. - Only use `uv tool install` only when specifically requested by the user. ### Pip interface **Use when:** Legacy workflows with `requirements.txt` or manual environment management, no `uv.lock` present. **Key commands:** ```bash uv venv uv pip install -r requirements.txt uv pip compile requirements.in -o requirements.txt uv pip sync requirements.txt # Platform independent resolution uv pip compile --universal requirements.in -o requirements.txt ``` **Important:** - Don't use the pip interface unless clearly needed. - Don't introduce new `requirements.txt` files. - Prefer `uv init` for new projects. ## Migrating from other tools ### pyenv → uv python ```bash pyenv install 3.12 → uv python install 3.12 pyenv versions → uv python list --only-installed pyenv local 3.12 → uv python pin 3.12 pyenv global 3.12 → uv python install 3.12 --default ``` ### pipx → uvx ```bash pipx run ruff → uvx ruff pipx install ruff → uv tool install ruff pipx upgrade ruff → uv tool upgrade ruff pipx list → uv tool list ``` ### pip and pip-tools → uv pip ```bash pip install package → uv pip install package pip install -r req.txt → uv pip install -r req.txt pip freeze → uv pip freeze pip-compile req.in → uv pip compile req.in pip-sync req.txt → uv pip sync req.txt virtualenv .venv → uv venv ``` ## Common patterns ### Don't use pip in uv projects ```bash # Bad pip install requests # Good uv add requests ``` ### Don't run python directly ```bash # Bad python script.py # Good uv run script.py ``` ```bash # Bad python -c "..." # Good uv run python -c "..." ``` ```bash # Bad python3.12 -c "..." # Good uvx python@3.12 -c "..." ``` ### Don't manually manage environments in uv projects ```bash # Bad python -m venv .venv source .venv/bin/activate # Good uv run <command> ``` ## Documentation For detailed information, read the official documentation: - https://docs.astral.sh/uv/llms.txt The documentation links to specific pages for each of these workflows.