python-monorepo-architecture

Designs cross-package boundaries and uv workspace wiring for multi-package Python monorepos.

1|1|Updated May 24, 2026
One-click install
npx skills add https://github.com/bm629/agent-skills --skill python-monorepo-architecture-bm629
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-monorepo-architecture
Source: https://github.com/bm629/agent-skills/tree/main/skills/python-monorepo-architecture
Command: npx skills add https://github.com/bm629/agent-skills --skill python-monorepo-architecture-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Splitting a Python repository into multiple packages often produces tangled cross-package imports, circular dependencies, and unclear public APIs, and uv workspaces cannot enforce import isolation between members. This Skill provides the architectural rules and wiring steps to structure a uv-workspace monorepo correctly. ## Core Features & Use Cases - Workspace wiring: Configures the root pyproject.toml with [tool.uv.workspace] members and [tool.uv.sources] workspace dependencies, with a single shared lockfile and --package targeting. - Dependency direction rules: Enforces an acyclic depend-inward graph where apps depend on the shared library, never on each other, with optional import-linter contracts for CI enforcement. - Safe extraction: Provides a safety-net-first sequence for carving a shared library out of an existing package while keeping the test suite green. - Use Case: A CLI and a web API both need the same domain logic. Use this Skill to create a libs/core shared library member, wire both apps to depend on it, define its public API boundary, and extract the shared code without breaking existing tests. ## Quick Start Use the python-monorepo-architecture skill to split my Python repo into a uv workspace with a shared core library and two app members.

Frequently Asked Questions about python-monorepo-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up a Python monorepo with uv workspaces?

Declare members as globs in the root pyproject.toml under [tool.uv.workspace], give each member its own pyproject.toml, and let members depend on each other via [tool.uv.sources] with workspace = true. uv maintains one shared lockfile and environment for the whole workspace.

How do I make one uv workspace member depend on another?

List the shared package in the member's dependencies and add [tool.uv.sources] with the package set to { workspace = true } so uv resolves it from the workspace as an editable install instead of PyPI. Omitting the source line makes uv try to fetch it from PyPI.

When should I split a Python repo into multiple packages?

Split only when two or more deployables genuinely share code or when a deployable benefits from an independently testable core. A single deployable with no reuse should stay one package, since splitting adds lockfile, wiring, and boundary overhead for no benefit.

Does uv enforce import boundaries between workspace members?

No. A uv workspace shares one virtual environment and Python has no dependency isolation, so a member can import a sibling's packages at runtime. Boundaries are kept by code review or by an import-linter contract using independence, forbidden, or layers contract types in CI.

How do I fix a circular import between packages in a monorepo?

Break the cycle by pushing the shared dependency down into the shared library, or invert it by passing the app-specific piece into the library as a parameter or interface. Never resolve it with an upward import from the library into an app.

Can uv workspace members use different Python versions?

No. A uv workspace enforces a single requires-python, computed as the intersection across all members. If members need divergent Python floors or conflicting dependency versions, use a path dependency or separate repositories instead of a workspace.