uv-expert_skill

Overview

This skill provides expert guidance for uv, the high-performance Python package and project manager written in Rust. It helps with installation, project setup, dependency management, virtual environments, tooling, and migration from pip/poetry/conda. Use it to get practical commands, workflows, and troubleshooting tips tailored to uv-centric development.

How this skill works

I inspect your project context and commands you mention, then recommend concrete uv commands, configuration patterns, and migration steps. I map common tasks (installing packages, creating venvs, running scripts, CI integration) to uv equivalents and propose fixes for errors like cache corruption or Python version conflicts. I also surface best practices for lockfiles, workspaces, and performance tuning.

When to use it

• Setting up a new Python project or initializing pyproject.toml with uv
• Replacing pip/poetry workflows with uv commands for dependency management
• Creating, pinning, or switching Python versions and virtual environments
• Optimizing dependency resolution, cache usage, or CI workflows
• Troubleshooting uv errors, verbose resolution output, or networking/index issues

Best practices

• Use uv init for new projects and keep uv.lock committed for reproducible builds
• Add runtime deps with uv add and dev deps with uv add --dev; run uv sync in CI
• Prefer uv run to manual venv activation; uv run works with pinned Python via uv python pin
• Use workspaces and uv sync --workspace for multi-package repositories to dedupe deps
• Let uv manage the cache; clear it with uv cache clean only when troubleshooting

Example use cases

• Migrate an existing pip-based project: uv add <package>, uv lock, uv sync
• Create a reproducible CI job: pip install uv, uv sync, uv run pytest
• Run a one-file script with inline deps: uv run script.py to auto-resolve dependencies
• Install and run developer tools without polluting global Python: uv tool install ruff; uv run ruff
• Dockerizing an app using uv.lock and uv sync for fast, cached installs