Skip to content

Dependency Management

Revel uses UV for all dependency management. Never use pip directly.

Never Use pip

Do not run pip install, pip freeze, or any pip command directly. All dependency operations go through UV.

Commands

Adding Dependencies

Dependency Type Command
Production uv add <package>
Development uv add --dev <package>
Development (explicit group) uv add --group dev <package> 
# Add a production dependency
uv add httpx

# Add a development-only dependency
uv add --dev pytest-randomly

Removing Dependencies

uv remove <package>

Syncing the Environment

Command Description
uv sync Install all dependencies from the lockfile (includes dev dependencies by default)
uv sync --group dev Explicitly include the dev dependency group

Tip

After pulling changes that modify pyproject.toml or uv.lock, run uv sync to ensure your local environment matches.

How It Works

UV manages dependencies through two files:

  • pyproject.toml: declares dependencies and their version constraints
  • uv.lock: the resolved lockfile with exact versions (committed to git)

This replaces the traditional requirements.txt / requirements-dev.txt workflow.

Why UV?

Benefit Details
Speed 10-100x faster than pip for installs and resolution
Deterministic resolution Lockfile guarantees identical environments everywhere
Automatic venv management Creates and manages .venv/ automatically
Better conflict detection Catches dependency conflicts early with clear error messages

Info

Contributors need to install UV before working on the project. Once UV is installed, run make setup to complete the environment configuration.