uv (Python Package Manager)

--- name: uv (Python Package Manager) description: Use when managing Python projects, dependencies, virtual environments, or need faster pip/poetry alternatives. Ideal for Python development workflows requiring speed and modern dependency resolution. category: dev metadata: author: skynet version: 1.0.0 --- # uv - Ultrafast Python Package Manager ## Core Commands ### Project Management ```bash # Create new project uv init my-project cd my-project # Initialize in existing directory uv init --app # Create application structure uv init --lib # Create library structure # Add dependencies uv add requests uv add "fastapi[all]>=0.68.0" uv add --dev pytest black uv add --optional docs sphinx # Remove dependencies uv remove requests uv remove --dev pytest ``` ### Virtual Environment Management ```bash # Create virtual environment uv venv uv venv .venv --python 3.11 uv venv --seed # Include pip, setuptools, wheel # Activate environment source .venv/bin/activate # Linux/Mac .venv\Scripts\activate # Windows # Install dependencies uv pip install -r requirements.txt uv pip install --editable . ``` ### Package Installation ```bash # Install packages (pip replacement) uv pip install package-name uv pip install "package>=1.0,<2.0" uv pip install -e git+https://github.com/user/repo.git # Install from requirements uv pip install -r requirements.txt --upgrade uv pip install -r requirements-dev.txt --no-deps # Generate requirements uv pip freeze > requirements.txt uv pip compile requirements.in # Generate .txt from .in ``` ## Lock File Management ```bash # Generate lock file uv lock # Install from lock file uv sync uv sync --dev # Include dev dependencies uv sync --no-dev # Exclude dev dependencies # Update dependencies uv lock --upgrade uv lock --upgrade-package requests ``` ## Running Commands ```bash # Run scripts in project environment uv run python script.py uv run pytest uv run --with requests -- python -c "import requests; print('OK')" # Run with specific Python version uv run --python 3.11 script.py # Run tools without installing uv tool run black . uv tool run --from flask flask run ``` ## Decision Trees ### Choosing Installation Method ``` New Python project? ├── Yes → uv init → uv add dependencies └── No → Existing project? ├── Has pyproject.toml → uv sync ├── Has requirements.txt → uv pip install -r requirements.txt └── Legacy setup → uv venv → uv pip install ``` ### Dependency Management Strategy ``` Project type? ├── Application → uv lock (commit lock file) ├── Library → uv add (no lock file in repo) └── Monorepo → uv workspace for multi-package setup ``` ## Common Workflows ### New Project Setup ```bash # Complete new project workflow uv init --app my-api cd my-api uv add fastapi uvicorn uv add --dev pytest black isort uv run uvicorn main:app --reload ``` ### Migrating from pip/poetry ```bash # From pip uv venv uv pip install -r requirements.txt uv pip freeze > uv-requirements.txt # From poetry uv init # Copy dependencies from pyproject.toml manually or: uv add $(poetry show --only=main --no-dev | awk '{print $1}') ``` ### CI/CD Pipeline ```bash # In CI/CD (GitHub Actions, etc.) uv sync --frozen # Fail if lock file is outdated uv run pytest uv run black --check . ``` ## Advanced Features ### Workspaces (Monorepo) ```toml # pyproject.toml [tool.uv.workspace] members = ["packages/*"] ``` ```bash uv add --package package-a requests uv sync --package package-b ``` ### Tool Management ```bash # Install tools globally uv tool install black uv tool install --python 3.11 mypy # List installed tools uv tool list # Upgrade tools uv tool upgrade black uv tool upgrade-all ``` ### Python Version Management ```bash # Install Python versions uv python install 3.11 3.12 uv python list # Pin Python version echo "3.11" > .python-version uv venv # Uses pinned version ``` ## Configuration ### pyproject.toml ```toml [tool.uv] dev-dependencies = [ "pytest>=7.0", "black", "isort" ] [tool.uv.sources] my-package = { git = "https://github.com/user/repo.git" } local-package = { path = "../local-pkg", editable = true } ``` ### Environment Variables ```bash export UV_INDEX_URL="https://pypi.org/simple" export UV_EXTRA_INDEX_URL="https://my-private-index.com" export UV_NO_CACHE=1 export UV_CACHE_DIR="/custom/cache" ``` ## Troubleshooting ### Common Errors **"No solution found when resolving dependencies"** ```bash # Check for conflicting requirements uv add --resolution=lowest-direct package-name # Or relax constraints uv add "package-name>=1.0" --upgrade ``` **"Failed to download package"** ```bash # Clear cache and retry uv cache clean uv pip install package-name --refresh # Use different index uv pip install --index-url https://pypi.org/simple package-name ``` **"Permission denied" on Windows** ```bash # Run as administrator or use user install uv pip install --user package-name # Or check antivirus blocking ``` **Lock file out of sync** ```bash # Regenerate lock file uv lock --upgrade # Or force sync uv sync --refresh ``` ### Performance Issues ```bash # Parallel installation uv pip install -r requirements.txt --compile # Skip dependency resolution uv pip install package-name --no-deps # Use local cache export UV_CACHE_DIR="/fast/ssd/cache" ``` ### Debug Mode ```bash # Verbose output uv -v pip install package-name uv -vv sync # Extra verbose # Dry run uv add --dry-run package-name ``` ## Migration Helpers ### From pip-tools ```bash # Replace pip-compile uv pip compile requirements.in -o requirements.txt # Replace pip-sync uv pip sync requirements.txt ``` ### From Poetry ```bash # Export poetry deps poetry export -f requirements.txt --output requirements.txt uv pip install -r requirements.txt # Convert pyproject.toml manually for uv format ``` ## Performance Benefits - **10-100x faster** than pip for resolution - **Parallel downloads** and installations - **Global cache** shared across projects - **Incremental resolution** for updates - **Memory efficient** dependency resolution Use `uv` as drop-in replacement for pip with significant speed improvements and modern Python project management features.