Northern-Thailand-Ping-River-Monitor/MIGRATION_TO_UV.md

Migration to uv

This document describes the migration from traditional Python package management (pip + requirements.txt) to uv, a fast Python package installer and resolver.

What Changed

Files Added

• pyproject.toml - Modern Python project configuration combining dependencies and metadata
• .python-version - Specifies Python version for uv
• scripts/setup_uv.sh - Unix setup script for uv environment
• scripts/setup_uv.bat - Windows setup script for uv environment
• This migration guide

Files Modified

• Makefile - Updated all commands to use uv run instead of direct Python execution

Files That Can Be Removed (Optional)

• requirements.txt - Dependencies now in pyproject.toml
• requirements-dev.txt - Dev dependencies now in pyproject.toml
• setup.py - Configuration now in pyproject.toml

Installation

Install uv

Unix/macOS:

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

Windows (PowerShell):

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

Setup Project

Unix/macOS:

# Run the setup script
chmod +x scripts/setup_uv.sh
./scripts/setup_uv.sh

# Or manually:
uv sync
uv run pre-commit install

Windows:

REM Run the setup script
scripts\setup_uv.bat

REM Or manually:
uv sync
uv run pre-commit install

New Workflow

Common Commands

Old Command	New Command	Description
pip install -r requirements.txt	uv sync --no-dev	Install production dependencies
pip install -r requirements-dev.txt	uv sync	Install all dependencies (including dev)
python run.py	uv run python run.py	Run the application
pytest	uv run pytest	Run tests
black src/	uv run black src/	Format code

Using the Makefile

The Makefile has been updated to use uv, so all existing commands work the same:

make install-dev    # Install dev dependencies with uv
make test          # Run tests with uv
make run-api       # Start API server with uv
make lint          # Lint code with uv
make format        # Format code with uv

Adding Dependencies

Production dependency:

uv add requests

Development dependency:

uv add --dev pytest

Specific version:

uv add "fastapi==0.104.1"

Managing Python Versions

uv can automatically manage Python versions:

# Install and use Python 3.11
uv python install 3.11
uv sync

# Use specific Python version
uv sync --python 3.11

Benefits of uv

1. Speed - 10-100x faster than pip
2. Reliability - Better dependency resolution
3. Simplicity - Single tool for packages and Python versions
4. Reproducibility - Lock file ensures consistent environments
5. Modern - Built-in support for pyproject.toml

Troubleshooting

Command not found

Make sure uv is in your PATH after installation. Restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

Lock file conflicts

If you encounter lock file issues:

rm uv.lock
uv sync

Python version issues

Ensure the Python version in .python-version is available:

uv python list
uv python install 3.11  # if needed

Rollback (if needed)

If you need to rollback to the old system:

1. Use the original requirements files:

   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   

2. Revert the Makefile changes to use python instead of uv run python

3. Remove uv-specific files:

   rm pyproject.toml .python-version uv.lock
   rm -rf .venv  # if created by uv
   

Additional Resources

• uv Documentation
• Migration Guide
• pyproject.toml Reference