uv-package-manager

# UV Package Manager Skill ## When to Activate Activate this skill when: - Creating new Python projects - Adding or removing dependencies - Running Python scripts or tools - Managing virtual environments - Setting up Python version management ## Why UV? - **10-100x faster** than pip (Rust implementation) - **Unified tool** - replaces pip, pip-tools, poetry, pyenv, virtualenv - **Reliable** - lock files for reproducible builds - **Modern** - built for current Python workflows ## Quick Commands ```bash # Project Management uv init # Create new project uv init --package my-lib # Create installable package # Dependencies uv add requests # Add dependency uv add --dev pytest # Add dev dependency uv remove package-name # Remove dependency # Running Code uv run script.py # Run Python script uv run pytest # Run installed tool uv run python -m module # Run module # Environment uv sync # Sync dependencies uv sync --frozen # Sync without updating lock uv lock # Update lock file uv python install 3.12 # Install Python version ``` ## Creating Projects ```bash # Standard project uv init my-project cd my-project # Package project (for libraries) uv init --package my-library # Specify Python version uv init --python 3.11 ``` ### Created Structure ``` my-project/ ├── .python-version # Python version ├── pyproject.toml # Project config ├── .venv/ # Virtual environment (auto-created) └── hello.py # Sample script ``` ## Adding Dependencies ```bash # Basic add uv add requests fastapi uvicorn # With version constraints uv add "django>=4.2,<5.0" uv add "requests==2.31.0" uv add "fastapi[all]" # Dev dependencies uv add --dev pytest black ruff mypy # From git uv add --git https://github.com/user/repo --branch develop ``` ## Running Scripts ```bash # Run Python script uv run script.py # Run with arguments uv run script.py --input data.csv # Run dev tools uv run pytest tests/ -v uv run black . uv run ruff check . # Run with temporary dependency uv run --with httpx fetch_data.py # Start Python REPL uv run python ``` ## Virtual Environment UV automatically manages virtual environments: ```bash # Created automatically on first use uv sync # First sync uv add package # First package add uv run script.py # First run # Manual creation uv venv uv venv --python 3.11 # Manual activation (rarely needed) source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows ``` ## Lock Files ```bash # Generate/update lock file uv lock # Sync from lock (normal) uv sync # Sync without updating (CI/CD) uv sync --frozen # Update specific package uv lock --upgrade-package requests # ALWAYS commit these files: # - pyproject.toml # - uv.lock # - .python-version ``` ## Python Version Management ```bash # List available versions uv python list # Install specific version uv python install 3.12 # Set project version echo "3.12" > .python-version ``` ## Migration from pip ```bash # Import requirements.txt uv init my-project cd my-project uv add -r requirements.txt # Import dev requirements uv add --dev -r requirements-dev.txt ``` ## Common pyproject.toml ```toml [project] name = "my-project" version = "0.1.0" requires-python = ">=3.11" dependencies = [ "fastapi>=0.100.0", "uvicorn>=0.20.0", ] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "black>=23.0.0", "ruff>=0.1.0", ] [tool.uv] dev-dependencies = [ "pytest>=7.0.0", ] ``` ## Best Practices ### DO ✅ - Commit `uv.lock` and `.python-version` - Use semantic versioning for dependencies - Use `--dev` for development tools - Use `uv run` instead of manual activation - Use `--frozen` in CI/CD ### DON'T ❌ - Commit `.venv/` directory - Use `*` for version constraints - Mix pip and uv in same project - Skip lock file updates after changes ## Troubleshooting ```bash # Clear cache uv cache clean # Verbose mode for debugging uv --verbose add package # Regenerate lock uv lock uv sync ``` ## Related Resources See `AgentUsage/uv_usage.md` for complete documentation including: - Docker integration patterns - Workspace support for monorepos - CI/CD configuration - Detailed migration guides