UV Package Manager Skill

Master UV for blazing-fast Python package management, virtual environment creation, and modern Python project workflows.

When to Use This Skill

Use UV package manager when you need:

• Fast dependency installation - 10-100x faster than pip

• Virtual environment management - Create and manage venvs effortlessly

• Project initialization - Start new Python projects quickly

• Dependency resolution - Reliable, reproducible dependency trees

• Lock file management - Ensure consistent environments across machines

• Python version management - Install and switch Python versions

Avoid when:

• Legacy systems requiring pip compatibility (rare)

• Conda-based scientific computing environments

• Docker images with pre-installed pip workflows

Installation

Linux/macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew

brew install uv

pip (if needed)

pip install uv

Core Capabilities

1. Project Initialization

Create a new Python project:

Initialize new project with pyproject.toml

uv init my-project cd my-project

Initialize in current directory

uv init

Initialize with specific Python version

uv init --python 3.11

Project structure created:

my-project/ ├── .python-version # Python version lock ├── pyproject.toml # Project configuration ├── README.md # Project readme └── src/ └── my_project/ └── init.py

2. Virtual Environment Management

Create and activate virtual environments:

Create venv (default .venv directory)

uv venv

Create with specific Python version

uv venv --python 3.11

Create with custom name

uv venv .venv-test

Activate (Linux/macOS)

source .venv/bin/activate

Activate (Windows)

.venv\Scripts\activate

Activate (Git Bash on Windows)

source .venv/Scripts/activate

List available Python versions:

List installed Python versions

uv python list

Install specific Python version

uv python install 3.12

Pin Python version for project

uv python pin 3.11

3. Dependency Management

Add dependencies:

Add a single package

uv add pandas

Add multiple packages

uv add numpy scipy matplotlib

Add with version constraints

uv add "pandas>=2.0,<3.0"

Add development dependencies

uv add --dev pytest pytest-cov ruff

Add optional dependencies

uv add --optional ml tensorflow torch

Add from git repository

uv add git+https://github.com/user/repo.git

Add local package in editable mode

uv add --editable ../my-local-package

Remove dependencies:

Remove a package

uv remove pandas

Remove dev dependency

uv remove --dev pytest

Sync dependencies:

Install all dependencies from pyproject.toml

uv sync

Sync including dev dependencies

uv sync --dev

Sync with optional dependencies

uv sync --extra ml

Sync all extras

uv sync --all-extras

4. Lock File Management

Understanding uv.lock:

Lock file is auto-generated on uv add/sync

Contains exact versions for reproducibility

Regenerate lock file

uv lock

Lock with specific Python version

uv lock --python 3.11

Update all dependencies to latest

uv lock --upgrade

Update specific package

uv lock --upgrade-package pandas

Lock file structure:

uv.lock (auto-generated, do not edit manually)

version = 1 requires-python = ">=3.9"

[[package]] name = "pandas" version = "2.2.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "numpy" }, { name = "python-dateutil" }, { name = "pytz" }, ]

5. Running Scripts and Commands

Run Python scripts:

Run script with project dependencies

uv run python script.py

Run module

uv run python -m pytest

Run with specific Python version

uv run --python 3.11 python script.py

Run tools:

Run pytest

uv run pytest tests/

Run ruff for linting

uv run ruff check src/

Run black for formatting

uv run black src/

Run any CLI tool

uv run mypy src/

6. pip Compatibility Mode

Use UV as a pip replacement:

Install packages (pip syntax)

uv pip install pandas numpy

Install from requirements.txt

uv pip install -r requirements.txt

Install in editable mode

uv pip install -e .

Compile requirements

uv pip compile requirements.in -o requirements.txt

Sync environment

uv pip sync requirements.txt

Freeze installed packages

uv pip freeze > requirements.txt

Show package info

uv pip show pandas

Complete Examples

Example 1: New Project Setup

#!/bin/bash

setup_project.sh - Initialize a new Python project with UV

PROJECT_NAME=${1:-"my-project"}

Create and enter project

uv init "$PROJECT_NAME" cd "$PROJECT_NAME"

Pin Python version

uv python pin 3.11

Add core dependencies

uv add pandas numpy pyyaml click

Add dev dependencies

uv add --dev pytest pytest-cov ruff mypy black isort

Add visualization (optional)

uv add --optional viz plotly matplotlib

Create project structure

mkdir -p src/"${PROJECT_NAME//-/_}" tests data docs

Create init.py

touch src/"${PROJECT_NAME//-/_}"/init.py

Create test file

cat > tests/test_example.py << 'EOF' def test_import(): """Test that package can be imported.""" import sys assert 'my_project' in sys.modules or True EOF

Create .gitignore

cat > .gitignore << 'EOF' .venv/ pycache/ *.pyc .pytest_cache/ .mypy_cache/ .ruff_cache/ dist/ *.egg-info/ .coverage htmlcov/ EOF

Run tests to verify setup

uv run pytest tests/ -v

echo "Project $PROJECT_NAME initialized successfully!" echo "Activate with: source .venv/bin/activate"

Example 2: Migrate from pip to UV

#!/bin/bash

migrate_to_uv.sh - Migrate existing project to UV

Backup existing requirements

cp requirements.txt requirements.txt.bak 2>/dev/null || true

Initialize UV project (if pyproject.toml doesn't exist)

if [ ! -f pyproject.toml ]; then uv init --no-readme fi

Add dependencies from requirements.txt

if [ -f requirements.txt ]; then echo "Migrating dependencies from requirements.txt..."

# Parse and add each dependency
while IFS= read -r line; do
    # Skip comments and empty lines
    [[ "$line" =~ ^#.*$ ]] && continue
    [[ -z "$line" ]] && continue

    # Add dependency
    uv add "$line" 2>/dev/null || echo "Skipped: $line"
done < requirements.txt

fi

Add dev dependencies from requirements-dev.txt

if [ -f requirements-dev.txt ]; then echo "Migrating dev dependencies..."

while IFS= read -r line; do
    [[ "$line" =~ ^#.*$ ]] && continue
    [[ -z "$line" ]] && continue
    uv add --dev "$line" 2>/dev/null || echo "Skipped: $line"
done < requirements-dev.txt

fi

Sync to ensure everything is installed

uv sync --dev

echo "Migration complete! Review pyproject.toml and uv.lock"

Example 3: CI/CD Pipeline with UV

.github/workflows/ci.yml

name: CI

on: push: branches: [main] pull_request: branches: [main]

jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.10", "3.11", "3.12"]

steps:
  - uses: actions/checkout@v4

  - name: Install UV
    uses: astral-sh/setup-uv@v4
    with:
      version: "latest"

  - name: Set up Python
    run: uv python install ${{ matrix.python-version }}

  - name: Install dependencies
    run: uv sync --dev

  - name: Run linting
    run: uv run ruff check src/

  - name: Run type checking
    run: uv run mypy src/

  - name: Run tests
    run: uv run pytest tests/ --cov=src --cov-report=xml

  - name: Upload coverage
    uses: codecov/codecov-action@v4
    with:
      files: ./coverage.xml

build: runs-on: ubuntu-latest needs: test steps: - uses: actions/checkout@v4

  - name: Install UV
    uses: astral-sh/setup-uv@v4

  - name: Build package
    run: uv build

  - name: Upload artifacts
    uses: actions/upload-artifact@v4
    with:
      name: dist
      path: dist/

Example 4: Multi-Environment Management

#!/bin/bash

manage_envs.sh - Manage multiple Python environments

Function to create environment for specific Python version

create_env() { local py_version=$1 local env_name=".venv-py${py_version//./}"

echo "Creating environment for Python $py_version..."
uv venv "$env_name" --python "$py_version"

# Install dependencies
source "$env_name/bin/activate"
uv sync
deactivate

echo "Created: $env_name"

}

Create environments for multiple Python versions

create_env 3.10 create_env 3.11 create_env 3.12

Run tests across all environments

echo "Running tests across environments..." for env in .venv-py*; do echo "Testing with $env..." source "$env/bin/activate" uv run pytest tests/ -q deactivate done

Example 5: Workspace-Hub Project Setup

#!/bin/bash

setup_workspace_project.sh - Setup project following workspace-hub patterns

PROJECT_NAME=${1:-"new-project"} TEMPLATE_REPO="workspace-hub/pyproject-starter"

Initialize with UV

uv init "$PROJECT_NAME" cd "$PROJECT_NAME"

Pin Python version (match workspace-hub standard)

uv python pin 3.11

Add workspace-hub standard dependencies

uv add
pyyaml
pandas
numpy
plotly
click

Add standard dev dependencies

uv add --dev
pytest
pytest-cov
ruff
mypy
black
isort
deepdiff

Create workspace-hub directory structure

mkdir -p
src/"${PROJECT_NAME//-/_}"
tests
docs
data/raw
data/processed
data/results
reports
config
scripts

Create standard files

touch src/"${PROJECT_NAME//-/_}"/init.py

Create conftest.py for pytest

cat > tests/conftest.py << 'EOF' """Pytest configuration and fixtures.""" import pytest from pathlib import Path

@pytest.fixture def project_root(): """Return project root directory.""" return Path(file).parent.parent

@pytest.fixture def data_dir(project_root): """Return data directory.""" return project_root / "data"

@pytest.fixture def test_data_dir(project_root): """Return test data directory.""" return project_root / "tests" / "data" EOF

Create CLAUDE.md for AI development

cat > CLAUDE.md << 'EOF'

Project Configuration

Development Commands

# Install dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Run linting
uv run ruff check src/

# Run formatting
uv run black src/ tests/
uv run isort src/ tests/

# Run type checking
uv run mypy src/

Project Structure

- src/
 - Source code

- tests/
 - Test files

- docs/
 - Documentation

- data/
 - Data files (raw, processed, results)

- reports/
 - Generated HTML reports

- config/
 - Configuration files
EOF

echo "Project $PROJECT_NAME created with workspace-hub patterns!"

## Best Practices

### 1. Version Pinning

```bash
# Always pin Python version for reproducibility
uv python pin 3.11

# Use version ranges in pyproject.toml
# [project]
# requires-python = ">=3.10,<3.13"

2. Lock File Hygiene

# Commit uv.lock to version control
git add uv.lock

# Update regularly
uv lock --upgrade

# Review changes before committing
git diff uv.lock

3. Dependency Groups

# pyproject.toml - organize dependencies logically
[project]
dependencies = [
    "pandas>=2.0",
    "numpy>=1.24",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1.0",
]
viz = [
    "plotly>=5.0",
    "matplotlib>=3.7",
]
ml = [
    "scikit-learn>=1.3",
    "tensorflow>=2.15",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0",
    "ruff>=0.1.0",
]

4. Scripts Configuration

# pyproject.toml - define project scripts
[project.scripts]
my-cli = "my_project.cli:main"

[tool.uv.scripts]
test = "pytest tests/ -v"
lint = "ruff check src/"
format = "black src/ tests/"
typecheck = "mypy src/"
all = ["lint", "typecheck", "test"]

5. Performance Tips

# Use parallel installation (default)
uv sync

# Cache packages globally
export UV_CACHE_DIR="$HOME/.cache/uv"

# Offline mode (use cached packages)
uv sync --offline

# Minimal install (no extras)
uv sync --no-dev --no-extras

Common Commands Reference

Command
Description

uv init

Initialize new project

uv venv

Create virtual environment

uv add <pkg>

Add dependency

uv add --dev <pkg>

Add dev dependency

uv remove <pkg>

Remove dependency

uv sync

Install all dependencies

uv lock

Update lock file

uv run <cmd>

Run command in venv

uv python list

List Python versions

uv python install

Install Python version

uv pip install

pip compatibility mode

uv build

Build package

uv publish

Publish to PyPI

Resources

- UV Documentation: https://docs.astral.sh/uv/

- UV GitHub: https://github.com/astral-sh/uv

- Migration Guide: https://docs.astral.sh/uv/guides/migration/

- pyproject.toml Spec: https://packaging.python.org/en/latest/specifications/pyproject-toml/

Use UV for all Python projects in workspace-hub!