UV Migration Guide

Complete guide for migrating to UV and Python 3.13

UV Migration Guide

This project has been migrated to use uv for Python dependency management and Python 3.13.

What Changed

1. Python Version

  • Before: Python 3.10+
  • After: Python 3.13+ (enforced via .python-version)

2. Package Manager

  • Before: pip and venv
  • After: uv (ultra-fast Python package installer and resolver)

3. Build Backend

  • Before: setuptools
  • After: hatchling (modern, standards-compliant build backend)

4. Virtual Environments

  • All .venv/ directories have been removed
  • uv manages virtual environments automatically

Prerequisites

Install uv

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

# Or using pip
pip install uv

# Or using pipx
pipx install uv

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

Verify Installation

uv --version

Getting Started

1. Sync Dependencies

The project uses a workspace configuration in the root pyproject.toml. To sync all dependencies:

# From the project root
uv sync

This will:

  • Create a virtual environment in .venv/
  • Install all workspace dependencies
  • Install all workspace member packages in development mode

2. Build All Packages

make build
# or
./build.sh

The build script now uses uv pip install instead of pip install.

3. Run Tests

make test
# or
./test.sh

The test script now uses uv run pytest to ensure tests run in the uv-managed environment.

4. Clean Build Artifacts

make clean

This now also removes any .venv/ directories.

Workspace Structure

The project uses uv’s workspace feature to manage multiple packages:

mlops-with-mlflow/
├── pyproject.toml          # Root workspace configuration
├── .python-version         # Python version specification (3.13)
├── uv.lock                 # Locked dependencies (generated)
└── src/
    ├── doe-library/        # Workspace member
    ├── io-library/         # Workspace member
    ├── feature-library/    # Workspace member
    ├── metrics-library/    # Workspace member
    ├── plot-library/       # Workspace member
    ├── hurricane-landfall/ # Workspace member
    └── mlflow-tf/          # Workspace member

Common Commands

Install a New Dependency

# Add to root project
uv add numpy

# Add to specific workspace member
cd src/doe-library
uv add scipy

Run a Script

# Using uv run ensures the correct environment
uv run python script.py

# Or activate the environment
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows
python script.py

Update Dependencies

# Update all dependencies
uv sync --upgrade

# Update specific package
uv add numpy@latest

Lock Dependencies

# Create/update uv.lock
uv lock

Benefits of uv

  1. Speed: 10-100x faster than pip
  2. Deterministic: Lock file ensures reproducible builds
  3. Workspace Support: Manage multiple packages in a monorepo
  4. Modern: Uses latest Python packaging standards
  5. Simple: Fewer commands, less configuration

Migration Checklist

  • Install uv
  • Remove all .venv/ directories
  • Create .python-version file
  • Create root pyproject.toml with workspace configuration
  • Update all package pyproject.toml files to require Python 3.13
  • Update build backend from setuptools to hatchling
  • Update build.sh to use uv pip install
  • Update test.sh to use uv run pytest
  • Update .gitignore to include .venv/
  • Update Makefile clean target
  • Run uv sync to create lock file
  • Run make build to verify builds work
  • Run make test to verify tests work

Troubleshooting

uv not found

# Make sure uv is in your PATH
export PATH="$HOME/.local/bin:$PATH"

Python 3.13 not available

# uv can install Python versions for you
uv python install 3.13

Workspace sync fails

# Try removing the lock file and resyncing
rm uv.lock
uv sync

Package installation fails

# Clear uv cache
uv cache clean

# Try again
uv sync

Further Reading

Support

For issues related to: