Dependency Management¶

Validibot uses uv for Python dependency management. All dependencies are declared in pyproject.toml and locked in uv.lock. This approach provides reproducible builds and fast installs.

Quick Reference¶

Dependency Categories¶

We organize dependencies into three groups:

Base Dependencies (both local and production)¶

These are the core packages needed to run the application. They go in the main [project.dependencies] section of pyproject.toml.

# Add a new base dependency
uv add django-extensions

# Add with a specific version
uv add "httpx>=0.28.0"

Dev-Only Dependencies¶

Development tools like pytest, mypy, and linters. These go in the [dependency-groups] section and are only installed when you use --group dev.

# Add a dev-only dependency
uv add --group dev pytest-cov

# Add multiple at once
uv add --group dev "ruff>=0.14" "mypy>=1.18"

Optional Extras¶

Optional feature dependencies that aren't needed for the base install. These use the [project.optional-dependencies] section.

# Add an optional extra dependency
uv add --optional cloud stripe

# Install with an extra
uv sync --extra cloud

Currently defined extras: cloud (stripe).

Installing Dependencies¶

For Local Development¶

# Install base + dev dependencies
uv sync --group dev

For Production¶

# Install base dependencies only (no dev tools)
uv sync

For Docker Builds¶

The Dockerfile runs uv sync --group dev --frozen which installs from the locked versions without updating the lock file.

Upgrading Dependencies¶

Upgrade a Specific Package¶

uv lock --upgrade-package django && uv sync

Upgrade All Packages¶

uv lock --upgrade && uv sync

Check for Outdated Packages¶

uv pip list --outdated

Working with validibot-shared¶

The validibot-shared package is published to PyPI and installed as a normal dependency. When validibot-shared changes:

1. Make changes in ../validibot-shared
2. Bump the version and publish to PyPI
3. In this project, run: uv lock --upgrade-package validibot-shared && uv sync

Common Workflows¶

Starting a New Feature¶

# Pull latest, sync dependencies
git pull
uv sync --group dev

# Load environment variables
source set-env.sh

# Run tests to verify setup
uv run pytest

Adding a New Library¶

# Add the dependency
uv add requests

# Commit pyproject.toml and uv.lock

Updating After a Merge¶

# If pyproject.toml or uv.lock changed
uv sync --group dev

Troubleshooting¶

"Package not found" After Install¶

Make sure you're using uv run to execute commands:

# Wrong - uses system Python
python manage.py runserver

# Right - uses uv's managed environment
uv run python manage.py runserver

Lock File Conflicts¶

If you get conflicts in uv.lock after a merge:

# Accept theirs and regenerate
git checkout --theirs uv.lock
uv lock

Dependency Resolution Errors¶

Try clearing the cache:

uv cache clean
uv lock

Reference¶

• uv Documentation
• pyproject.toml Specification