Skip to content

How to set up a Python monorepo with uv workspaces

A uv workspace lets multiple Python packages share a single repository, a single lockfile, and a single virtual environment. This is the standard approach for monorepos where packages depend on each other and need to stay in sync.

Create the workspace root

Initialize a bare project to serve as the workspace root:

uv init --bare monorepo
cd monorepo

This writes a pyproject.toml without scaffold code. If the root will not be imported or published, make it a virtual workspace by replacing the generated [project] table with the workspace configuration:

[tool.uv.workspace]
members = [
    "packages/*",
]

A virtual workspace root has no installable package or runtime [project.dependencies], although it can define shared dependency groups for development tools. In this example, each member declares its own test dependencies.

Add workspace members

Create packages inside a packages/ directory. Use --lib for libraries (packages meant to be imported) and --app for applications (packages meant to be run):

uv init --lib packages/shared-lib
uv init --app packages/worker-app
uv init --app packages/api-service

When uv init detects a pyproject.toml in a parent directory, it automatically adds the new package as a workspace member. If no [tool.uv.workspace] table exists yet, uv creates one. After running these commands, the root pyproject.toml will contain:

[tool.uv.workspace]
members = [
    "packages/shared-lib",
    "packages/worker-app",
    "packages/api-service",
]

Use glob patterns for members

Listing each member individually becomes tedious as the workspace grows. Replace the explicit list with a glob:

[tool.uv.workspace]
members = [
    "packages/*",
]

Any directory under packages/ that contains a pyproject.toml will be treated as a workspace member. New packages added later are picked up automatically.

Tip

To exclude a directory from an otherwise broad glob, use the exclude key:

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/legacy-app"]

Wire up cross-package dependencies

To make worker-app depend on shared-lib, use uv add with the --package flag:

uv add --package worker-app shared-lib

This adds two entries to packages/worker-app/pyproject.toml:

[project]
dependencies = [
    "shared-lib",
]

[tool.uv.sources]
shared-lib = { workspace = true }

The workspace = true source directive tells uv to resolve shared-lib from the local workspace instead of PyPI. The library is installed in editable mode, so changes to shared-lib are immediately visible to worker-app without reinstalling.

Share dependency sources across all members

Any [tool.uv.sources] entries in the workspace root pyproject.toml apply to every member by default. This is useful for pinning a fork or private registry across the entire workspace:

# Root pyproject.toml
[tool.uv.sources]
my-internal-lib = { url = "https://artifacts.example.com/my-internal-lib-1.0.tar.gz" }

Every member that depends on my-internal-lib will use this source without repeating the configuration. A member can override a root source by defining its own [tool.uv.sources] entry for the same package.

Lock and sync the workspace

A workspace uses a single uv.lock at the root. Running uv lock resolves dependencies for all members together:

uv lock

The lockfile records every member and its resolved dependencies. This guarantees that all packages in the workspace use the same version of every shared dependency.

To install all members into the shared virtual environment (rather than just the workspace root):

uv sync --all-packages

The .venv directory lives at the workspace root, not inside individual members.

To install only a specific member and its dependencies:

uv sync --package worker-app

This is useful in CI where each job only needs one application’s dependencies installed.

Run commands in specific packages

Use --package to target a specific member:

uv run --package worker-app python -c "from shared_lib import hello; print(hello())"

This ensures the command runs with worker-app and its dependencies available. The same flag works with other uv commands like uv add and uv remove.

For tests, declare pytest as a development dependency of each member that has tests:

uv add --dev --package shared-lib pytest
uv add --dev --package worker-app pytest
uv add --dev --package api-service pytest

Once each member has a tests/ directory, run its suite from the workspace root with that member’s declared dependencies:

uv run --package shared-lib pytest packages/shared-lib/tests
uv run --package worker-app pytest packages/worker-app/tests
uv run --package api-service pytest packages/api-service/tests

Each --package command selects the member and installs its dependencies before running pytest. The shared .venv does not mean every member is installed by a root-level uv run pytest. Run these commands separately in CI if each member needs its own result.

Realistic example

Consider a monorepo with a shared library used by two applications:

    • pyproject.toml
    • uv.lock
        • pyproject.toml
            • __init__.py
          • test_shared_lib.py
        • pyproject.toml
            • __init__.py
          • test_worker.py
        • pyproject.toml
            • __init__.py
          • test_api.py

The root pyproject.toml defines the workspace:

[tool.uv.workspace]
members = [
    "packages/*",
]

Both worker-app and api-service depend on shared-lib:

# packages/worker-app/pyproject.toml
[project]
name = "worker-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "shared-lib",
]

[tool.uv.sources]
shared-lib = { workspace = true }

Running uv lock produces a single lockfile that resolves shared-lib along with any external dependencies from both applications.

Handle Python version constraints

uv computes the intersection of all members’ requires-python values to determine the workspace’s supported Python range. If shared-lib requires >=3.10 and worker-app requires >=3.12, the workspace resolves against >=3.12.

This means adding a member with a narrow Python requirement tightens the constraint for the entire workspace. If that becomes a problem, the package with the incompatible requirement may belong outside the workspace.

Know when not to use workspaces

Workspaces work well when all members can share a single virtual environment and a single lockfile. They are the wrong tool when:

  • Members need conflicting dependency versions. All workspace members resolve together. If worker-app needs requests==2.28 and api-service needs requests==2.31, the resolver will fail. In this case, keep the projects in separate repositories (share dependencies between them with [tool.uv.sources]) or use separate pyproject.toml files outside the workspace.
  • Members need isolated virtual environments. A workspace has one .venv at the root. If packages must run in separate environments (for example, because they target different Python versions), workspaces cannot provide that isolation.
  • Members must guarantee strict import boundaries. Python has no dependency isolation at runtime. A workspace member can import any package installed in the shared .venv, including dependencies declared only by another member. If enforcing that each package uses only its declared dependencies is critical, use path dependencies with separate virtual environments instead of a workspace.

Workspaces also do not decide the installed import names. If several workspace members should publish under one shared import prefix, such as acme.storage and acme.billing, pair the workspace with namespace packages. If each member has its own import name, keep them as regular packages.

Last updated on