# Python Monorepo

> Python monorepos with uv workspaces, package layouts, namespace packages, Docker, and CI. Use for uv workspace setup or troubleshooting, explicit workspace dependencies, multi-package pyproject.toml design, package build/publish, or containerizing Python workspace applications. For standalone uv tooling, use python-build-tools.

- Skill: `martinffx/python-monorepo` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add martinffx/python-monorepo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martinffx/python-monorepo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: martinffx (https://skillmd.com/u/martinffx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/martinffx/python-monorepo

---


# Python Monorepo with uv Workspaces

Modern Python monorepo architecture using `uv` for workspace management and `mise` for Python version and task orchestration.

## Core Concepts

**Monorepo**: Single repository containing multiple related packages and applications

**uv workspace**: Python's answer to npm/pnpm workspaces
- Single lock file for entire repo
- Shared virtual environment
- Cross-package dependency resolution

## Directory Structure

```
my-monorepo/
├── .mise.toml           # Python version + task runner
├── pyproject.toml       # Root workspace config
├── uv.lock              # Unified lock file
├── apps/                # Deployable applications
│   ├── api/
│   └── worker/
└── packages/            # Shared libraries
    ├── core/
    └── utils/
```

## Workspace Configuration

**Root pyproject.toml:**

```toml
[project]
name = "my-monorepo"
version = "0.1.0"
requires-python = ">=3.12"

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

[dependency-groups]
dev = [
    "pytest",
    "ruff",
    "basedpyright",
]
```

See `references/workspace-config.md` for detailed configurations.

## Package Linking

Workspace packages reference each other by distribution name:

**packages/utils/pyproject.toml:**
```toml
[project]
name = "my-utils"
dependencies = ["my-core"]

[tool.uv.sources]
my-core = { workspace = true }
```

**apps/api/pyproject.toml:**
```toml
[project]
name = "my-api"
dependencies = ["my-core", "my-utils", "fastapi>=0.100.0"]

[tool.uv.sources]
my-core = { workspace = true }
my-utils = { workspace = true }
```

## Cross-Package Import

**packages/core/src/my_core/entities.py:**
```python
class User:
    def __init__(self, email: str):
        self.email = email
```

**apps/api/src/my_api/main.py:**
```python
from my_core.entities import User  # Import from workspace package

def run() -> None:
    # App code...
```

## Dependency Direction (Critical)

```
apps/ → packages/  (Apps depend on packages)
packages/ ⇏ apps/  (Never the reverse)
```

**Rules:**
- Apps can depend on packages
- Packages can depend on other packages
- Packages should not normally depend on deployable apps; allow an exception only when the architecture explicitly requires it.
- Avoid circular dependencies

## mise Task Runner

**.mise.toml:**

```toml
[tools]
python = "3.14"

[tasks.check]
depends = ["lint", "typecheck", "test"]

[tasks.lint]
run = "uv run ruff check ."
```

**Usage:** `mise run check`

## Core uv Commands

```bash
uv sync                           # Root project and its dependency closure
uv sync --all-packages            # Every workspace member
uv add fastapi --package my-api   # Add to specific package
uv add my-core --package my-api   # Add workspace package
uv run pytest                      # Run tests
uv lock --upgrade                 # Update dependencies
```

## Best Practices

1. Single lock file at root
2. Shared dev tools in root dependency groups
3. Pin Python version with mise
4. Apps depend on packages only
5. Use namespace packages for logical grouping (optional)

## References

For detailed patterns:
- [Workspace configuration](references/workspace-config.md) - sources, commands, and version policy
- [Docker](references/docker.md) - reproducible, non-root workspace images
- [Namespace packages](references/namespace-packages.md) - PEP 420 package layouts