UV Management

Quick reference for uv - the fast Python package installer and environment manager.

Installation

Install UV

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

# Or with pip
pip install uv

# Verify installation
uv --version

Project Initialization

Create New Project

# Initialize new project
uv init project-name

# Initialize in current directory
uv init

# With specific Python version
uv init --python 3.11

Project Structure Created

project-name/
├── pyproject.toml    # Project configuration
├── .python-version   # Python version specification
└── src/
    └── project_name/
        └── __init__.py

Virtual Environment

Create Virtual Environment

# Create venv (automatic with uv)
uv venv

# With specific Python version
uv venv --python 3.11

# With custom name
uv venv .venv-custom

# Activate (same as regular venv)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Python Version Management

# List available Python versions
uv python list

# Install specific Python version
uv python install 3.11

# Pin Python version for project
uv python pin 3.11

Package Management

Install Packages

# Install single package
uv pip install package-name

# Install specific version
uv pip install package-name==1.2.3

# Install from requirements.txt
uv pip install -r requirements.txt

# Install from pyproject.toml
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

Add Dependencies (Modern Way)

# Add package to project
uv add numpy

# Add with version constraint
uv add "numpy>=1.24,<2.0"

# Add multiple packages
uv add numpy pandas matplotlib

# Add as dev dependency
uv add --dev pytest black ruff

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

Remove Packages

# Remove package
uv remove package-name

# Remove dev dependency
uv remove --dev pytest

Update Packages

# Update single package
uv pip install --upgrade package-name

# Update all packages
uv pip install --upgrade -r requirements.txt

# Sync dependencies (recommended)
uv sync

Dependency Management

Lock Dependencies

# Generate lock file
uv lock

# Lock and sync
uv lock --sync

Export Requirements

# Export to requirements.txt
uv pip freeze > requirements.txt

# Export from pyproject.toml
uv export --format requirements-txt > requirements.txt

Running Commands

Run Python

# Run Python script
uv run python script.py

# Run module
uv run -m module_name

# Run with arguments
uv run python script.py --arg value

Run Tools

# Run pytest
uv run pytest

# Run black
uv run black .

# Run ruff
uv run ruff check .

# Run any tool
uv run tool-name [args]

VRP Project Setup

Initial Project Setup

# 1. Create project directory
mkdir vrp-toolkit
cd vrp-toolkit

# 2. Initialize with uv
uv init

# 3. Create virtual environment
uv venv

# 4. Activate environment
source .venv/bin/activate

# 5. Install core dependencies
uv add numpy pandas matplotlib networkx

# 6. Install dev dependencies
uv add --dev pytest black ruff ipython jupyter

# 7. Install OSMnx (for real map support)
uv add osmnx geopandas

# 8. Install package in editable mode
uv pip install -e .

pyproject.toml for VRP Toolkit

[project]
name = "vrp-toolkit"
version = "0.1.0"
description = "Reusable VRP/PDPTW solving framework"
requires-python = ">=3.8"
dependencies = [
    "numpy>=1.24.0",
    "pandas>=2.0.0",
    "matplotlib>=3.7.0",
    "networkx>=3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "ipython>=8.0.0",
    "jupyter>=1.0.0",
]
osmnx = [
    "osmnx>=1.6.0",
    "geopandas>=0.14.0",
    "folium>=0.15.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.black]
line-length = 100
target-version = ["py38"]

Install All Dependencies

# Install main dependencies
uv add numpy pandas matplotlib networkx

# Install dev tools
uv add --dev pytest black ruff ipython jupyter

# Install OSMnx group
uv add osmnx geopandas folium

# Or install from pyproject.toml
uv sync

Common Workflows

Daily Development

# Activate environment
source .venv/bin/activate

# Run tests
uv run pytest

# Format code
uv run black .

# Lint code
uv run ruff check .

# Run Jupyter
uv run jupyter lab

Add New Dependency

# Add package
uv add package-name

# Test it works
uv run python -c "import package_name; print('OK')"

# Commit updated pyproject.toml
git add pyproject.toml uv.lock
git commit -m "chore: add package-name dependency"

Clean Install

# Remove existing environment
rm -rf .venv

# Recreate
uv venv

# Reinstall all dependencies
uv sync

# Verify
uv run python -c "import numpy; print(numpy.__version__)"

Comparison with pip/venv

python -m venv .venv

uv venv

source .venv/bin/activate

pip install package

uv add package

pip install -r requirements.txt

uv pip install -r requirements.txt

pip freeze > requirements.txt

uv pip freeze > requirements.txt

python -m pytest

uv run pytest

Key Advantages of UV:

• ⚡ 10-100x faster than pip
• 🔒 Built-in dependency locking
• 🐍 Python version management
• 📦 Cleaner dependency specification in pyproject.toml

Additional Resources

Troubleshooting

Common issues and solutions: See troubleshooting.md

• UV not found after install
• Wrong Python version
• Dependency conflicts
• Package not found

Advanced Usage

Power user features: See advanced.md

• Multiple environments
• Dependency groups
• Build and publish
• Integration with other skills

Migration from pip

Convert existing projects: See migration.md

• Convert requirements.txt to pyproject.toml
• Migrate existing project step-by-step
• pip vs UV comparison

Quick Reference

uv init

uv venv

uv add package

uv add --dev tool

uv sync

uv run python script.py

uv run pytest

uv sync --upgrade

uv lock

uv pip freeze > requirements.txt

uv python install 3.11

uv python pin 3.11