python-uv_skill

Overview

This skill provides concise, practical guidance for using uv — a Rust-written, extremely fast Python package and project manager that replaces pip, virtualenv, pipx, poetry, and pyenv workflows. It explains project initialization, dependency and Python-version management, running code, tool handling, and CI/Docker integration. Use it to speed up installs, simplify environments, and standardize reproducible builds.

How this skill works

uv creates and manages project environments, a lockfile, and per-project Python versions. Commands like uv add, uv remove, uv sync, and uv lock modify dependencies and the uv.lock file. uv run executes scripts and commands inside the project environment without activating a venv, auto-syncing by default. uv python and uv tool replace pyenv and pipx behaviors for interpreters and global CLI tools.

When to use it

• Starting a new Python project and generating a standard layout quickly
• Replacing pip/virtualenv/poetry for faster install and reproducible locks
• Running scripts or test suites without manually activating virtual environments
• Managing multiple Python versions per machine or per project
• Running one-off CLI tools or installing global developer tools reliably
• Building CI pipelines or Docker images that need locked, repeatable installs

Best practices

• Use uv init to scaffold projects and commit pyproject.toml and uv.lock to version control
• Prefer uv run instead of activating venvs; it auto-syncs and is faster
• Use uv lock and uv sync --locked in CI to ensure reproducible builds
• Separate dev dependencies with --dev and use --no-dev in production builds
• Use uvx for ephemeral tool runs and uv tool install for persistent developer tools
• Avoid mixing pip and uv in the same project to prevent inconsistent environments

Example use cases

• Create a FastAPI app: uv init, uv add fastapi uvicorn, uv add --dev pytest; run with uv run uvicorn main:app --reload
• Migrate from requirements.txt: uv init; uv add -r requirements.txt; commit uv.lock instead of requirements.txt
• Run a script with temporary deps: uv run --with pandas --with matplotlib script.py or embed deps with PEP723 inline metadata
• CI setup: install uv, uv python install, uv sync --locked --all-extras --dev, uv run pytest
• Docker production image: copy pyproject.toml and uv.lock, run uv sync --locked --no-dev to install pinned deps efficiently