Large Python codebases usually start as a single repository with a monolithic setup. Over time, teams split services, internal shared libraries, and CLI tools into separate directories within the same repository. Dependency management quickly becomes a bottleneck. Traditional tools like pip and poetry take minutes to resolve dependency graphs across multiple packages. That delay compounds every time a CI runner spins up or a developer runs a test suite. It's painful.
Switching your enterprise Python stack to uv changes the math entirely. Written in Rust, it replaces pip, virtualenv, poetry, and pip-tools with a single binary that operates at system speeds. If you're already managing complex deployment pipelines, you'll want to review Production Python Dependencies With UV and Lockfiles for baseline configurations before jumping into multi-package monorepos. Don't skip those fundamentals.
Memory usage drops. CPU spikes disappear. Your CI pipelines finish before you can context-switch to Slack. That's what happens when you remove redundant file IO and Python-level graph parsing from your build loop.
Configuring Workspace Manifests
A workspace groups multiple local packages so they share a single virtual environment and lockfile. Instead of maintaining disjointed requirements files in every subdirectory, you define a root pyproject.toml that points to your workspace members. This setup ensures that all internal packages reference each other correctly without publishing them to an internal index during development. It's clean.
Here's how you structure the root manifest for an application containing an API service and a shared core library:
[workspace]
members = [
"services/api",
"libs/core"
]
[tool.uv]
package = false
Each member package retains its own pyproject.toml file specifying its individual external requirements. When you run commands from the root directory, uv calculates a unified lockfile across all members simultaneously. If you need to isolate dependencies further or compare alternative dependency tooling choices, check Python venv vs uv vs Poetry: Choosing for Production for detailed performance trade-offs.
You won't have to worry about circular references between internal packages breaking the installation phase. The resolver handles workspace topology natively. It builds a directed acyclic graph of your local packages alongside external dependencies from PyPI. If you introduce a cycle, it aborts instantly with a descriptive error. You'll catch architectural mistakes before writing any application logic.
Resolving and Locking Dependencies
Generating the lockfile happens through the CLI. Unlike traditional resolvers that query PyPI sequentially, uv lock processes the entire dependency graph concurrently. It reads every member package specification and writes a deterministic uv.lock file at the root of your repository. It's fast.
Run the following command in your terminal to generate or update the lockfile:
uv lock
The resulting lockfile pins exact versions and cryptographic hashes for every package, including transitive dependencies. This guarantees that your local development environment matches your production container precisely. If a developer adds a conflicting requirement in one of the workspace members, the resolver fails immediately with a clear error message pointing out the exact version mismatch.
You'll also notice that manual intervention during dependency upgrades becomes rare. Running uv lock --upgrade-package requests targets a single library and bumps its transitive tree without touching unrelated subsystems. It saves hours of manual auditing when security advisories force targeted patches across a large fleet of microservices.
Deploying Workspaces in CI and Production
Moving from local development to production builds requires a slightly different approach. You don't want to copy the entire monorepo into every microservice container image if you only need a specific service and its dependent internal libraries. The sync command allows you to target specific members or install everything cleanly into a production container. It's efficient.
Here's a multi-stage Dockerfile snippet for building a containerized service from a workspace:
FROM python:3.15-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock /
COPY services/api/pyproject.toml services/api/
COPY libs/core/pyproject.toml libs/core/
RUN uv sync --frozen --no-dev --package api
FROM python:3.15-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]
The --frozen flag ensures that uv fails if the lockfile is out of sync with the manifests, preventing silent drift during image builds. Caching dependency layers correctly reduces build times from several minutes to mere seconds. You'll spend less time waiting on container registries and more time shipping features.
Debugging production failures also gets easier because the environment layout matches across environments byte for byte. No mysterious C-extension compilation errors due to missing system headers or mismatched toolchain versions. Everything is contained within the virtual environment layout generated by the lockfile.












