UV_USAGE.md

UV Dependency Management Guide

This project now uses UV for fast, reliable Python package management.

Quick Start

Install UV

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

Initialise uv for using external dependencies not installable in uv

uv venv --system-site-packages

Install Project Dependencies

# Install all runtime dependencies
uv sync

# Install with documentation dependencies
uv sync --extra docs

# Install with development dependencies  
uv sync --extra dev

# Install all optional dependencies
uv sync --all-extras

Running Python Scripts

# Run a script using the project's virtual environment
uv run python src/HL/main.py

# Run a script directly (if defined in pyproject.toml)
uv run covapsy-main

Managing Dependencies

Add a new dependency

# Add runtime dependency
uv add numpy

# Add development dependency
uv add --dev pytest

# Add documentation dependency
uv add --optional docs mkdocs

Remove a dependency

uv remove package-name

Update dependencies

# Update all packages
uv lock --upgrade

# Update specific package
uv add package-name@latest

Virtual Environment Management

UV automatically manages virtual environments. You can also:

# Activate the virtual environment manually
source .venv/bin/activate

# Or run commands directly
uv run python your_script.py

Lock File

The uv.lock file pins exact versions for reproducible builds. Commit this file to version control.

Migration from pip

The project dependencies have been moved from requirements.txt to pyproject.toml. The old requirements.txt is kept for reference but should not be used for installation.

Old way (pip):

pip install -r requirements.txt

New way (UV):

uv sync

Benefits of UV

• Fast: 10-100x faster than pip
• Reliable: Deterministic resolution with lock files
• Cross-platform: Works on Linux, macOS, Windows
• Drop-in replacement: Compatible with existing Python tooling
• Modern: Built in Rust with modern dependency resolution