onyx/backend/requirements

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:

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

2. Adding/Updating Dependencies

DO NOT edit the .txt files directly! Instead:

1. Edit pyproject.toml
2. Add/update/remove dependencies in the appropriate section:
   • [dependency-groups] for dev tools
   • [project.dependencies] for shared dependencies (used by both backend and model_server)
   • [project.optional-dependencies.backend] for backend-only dependencies
   • [project.optional-dependencies.model_server] for model_server-only dependencies (ML packages)
   • [project.optional-dependencies.ee] for EE features
3. 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:

uv lock
uv export --no-emit-project --no-default-groups --no-hashes --extra 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 --extra ee -o backend/requirements/ee.txt
uv export --no-emit-project --no-default-groups --no-hashes --extra 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.

# For everything (most common)
uv sync --all-extras

# For backend production (shared + backend dependencies)
uv sync --extra backend

# For backend development (shared + backend + dev tools)
uv sync --extra backend --extra dev

# For backend with EE (shared + backend + ee)
uv sync --extra backend --extra ee

# For model server (shared + model_server, NO backend deps!)
uv sync --extra model_server

uv aggressively ignores active virtual environments and prefers the root virtual environment. When working in workspace packages, be sure to pass --active when syncing the virtual environment:

cd backend/
source .venv/bin/activate
uv sync --active
uv run --active ...

5. Upgrading Dependencies

Upgrade specific packages:

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

Review changes carefully before committing!