Requirements Management with uv

This directory is kept for backwards compatibility with existing Docker builds.

Overview

We use pyproject.toml as the single source of truth for all dependencies, with a unified uv.lock file for resolved versions.

Why this approach?

✅ Single source of truth: All dependencies defined in pyproject.toml
✅ No duplication: Dependencies shared across environments are only listed once
✅ Unified lock file: All versions resolved together - guaranteed compatible
✅ Fast: uv is 10-100x faster than pip-tools
✅ Reproducible builds: Lock file pins all transitive dependencies
✅ Easy updates: Change pyproject.toml, commit, done!

File Structure

pyproject.toml                      # SOURCE OF TRUTH - edit this!
uv.lock                             # Unified lock file (all versions)
backend/
└── requirements/                   # Legacy .txt files (for Docker compat)
    ├── default.txt
    ├── dev.txt
    ├── ee.txt
    ├── model_server.txt
    └── combined.txt

Workflow

1. Installing uv

If you don't have uv installed:

bash

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

2. Adding/Updating Dependencies

DO NOT edit the .txt files directly! Instead:

Edit pyproject.toml
Add/update/remove dependencies in the appropriate section:
- [project.dependencies] for shared dependencies (used by both backend and model_server)
- [dependency-groups.backend] for backend-only dependencies
- [dependency-groups.dev] for dev tools
- [dependency-groups.ee] for EE features
- [dependency-groups.model_server] for model_server-only dependencies (ML packages)
Commit your changes - pre-commit hooks will automatically regenerate the lock file and requirements

3. Generating Lock File and Requirements

The lock file (uv.lock) and requirements files are automatically generated by pre-commit hooks when you commit changes to pyproject.toml:

uv-lock: Runs uv lock to resolve dependencies into uv.lock
uv-export: Exports requirements to the .txt files in this directory

To manually regenerate:

bash

uv lock
uv export --no-emit-project --no-default-groups --no-hashes --group backend -o backend/requirements/default.txt
uv export --no-emit-project --no-default-groups --no-hashes --group dev -o backend/requirements/dev.txt
uv export --no-emit-project --no-default-groups --no-hashes --group ee -o backend/requirements/ee.txt
uv export --no-emit-project --no-default-groups --no-hashes --group model_server -o backend/requirements/model_server.txt

4. Installing Dependencies

If enabled, all packages are installed automatically by the uv-sync pre-commit hook when changing branches or pulling new changes.

bash

# For development (most common) — installs shared + backend + dev + ee
uv sync

# For backend production only (shared + backend dependencies)
uv sync --no-default-groups --group backend

# For model server (shared + model_server, NO backend deps!)
uv sync --no-default-groups --group model_server

5. Upgrading Dependencies

Upgrade specific packages:

Edit version in pyproject.toml, then commit
Pre-commit hooks will automatically regenerate lock and requirements files

Review changes carefully before committing!