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

Task Traditional UV

Create venv python -m venv .venv

uv venv

Activate source .venv/bin/activate

Same

Install package pip install package

uv add package

Install requirements pip install -r requirements.txt

uv pip install -r requirements.txt

Freeze deps pip freeze > requirements.txt

uv pip freeze > requirements.txt

Run tool 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

Task Command

Init project uv init

Create venv uv venv

Add package uv add package

Add dev dep uv add --dev tool

Install all uv sync

Run script uv run python script.py

Run tool uv run pytest

Update all uv sync --upgrade

Lock deps uv lock

Export reqs uv pip freeze > requirements.txt

Python version uv python install 3.11

Pin Python uv python pin 3.11