ADR-0008: Python Dependency Management with uv

Context

The Python Project Structure pattern originally prescribed Poetry for dependency management. At the time, Poetry was selected for team familiarity and production maturity, with a note to revisit the decision within 6 months.

Since then, uv has been evaluated and adopted across multiple Ontopix repositories:

• maxcolchon — monorepo with multiple Python projects, migrated from Poetry to uv. CI workflow times dropped from ~50s to ~20s (60% reduction). Workspace support ([tool.uv.workspace]) replaced manual path dependency workarounds.
• stylebook — using uv for Python tooling.
• audit-utils — using uv on the v1.0b1 branch, confirmed working well by @apuigsech.

The evaluation surfaced clear advantages over Poetry in every dimension that matters for Ontopix workloads:

Decision

Adopt uv as the standard Python dependency and project management tool for all Ontopix repositories. Poetry is no longer the recommended tool for new projects.

Existing Poetry-based projects SHOULD migrate to uv. Migration is not urgent for stable projects with no active development, but any project receiving active work should migrate at the next convenient opportunity.

The Taskfile contract abstracts the underlying tool, so the migration is transparent to consumers of the operational interface.

Implementation

• Update the Python Project Structure pattern to prescribe uv instead of Poetry.
• Use PEP 621 [project] metadata instead of [tool.poetry].
• Use uv.lock instead of poetry.lock.
• Use uv run instead of poetry run in Taskfile tasks and CI workflows.
• Use uv python install to pin Python versions instead of relying on pyenv.
• For monorepos, use [tool.uv.workspace] for multi-project setups.

Consequences

Positive

• CI times reduced by 50-60% based on measured evidence from maxcolchon migration.
• Native workspace support eliminates monorepo workarounds.
• PEP 621 compliance means pyproject.toml is portable across tools — no vendor lock-in.
• Built-in Python version management removes the pyenv dependency.
• Single tool replaces Poetry + pyenv.

Negative / Trade-offs

• uv is younger (~2 years) than Poetry (~6 years), though it is production-ready and backed by Astral (ruff maintainers).
• Team members familiar with Poetry will need to learn uv commands (low friction — commands are similar).
• Existing poetry.lock files must be regenerated as uv.lock during migration.

Evidence

• Issue #7 — Poetry vs. uv — original evaluation
• maxcolchon CI comparison — 50% CI speedup (20s vs 50s)
• audit-utils adoption — independent confirmation by @apuigsech

Related

• Pattern: Python Project Structure — updated to reflect this decision
• uv Documentation
• PEP 621 — Storing project metadata in pyproject.toml