---
id: hatch-polylith-bricks
version: "1.5.7"
license: MIT
license_treatment: permissive
maintenance: active
---

# hatch-polylith-bricks — Hatch build hook plugin for Polylith

License: permissive · Maintenance: active · Downloads: 299.6K/mo

## What it is and what it does

This package is a Hatch build hook that bridges Polylith architecture—a modular monorepo pattern—with Python packaging. It reads brick definitions from your pyproject.toml (paths to bases and components in your Polylith workspace) and ensures they are correctly included in built wheels and source distributions. The hook also solves a real packaging problem: when multiple libraries built from the same monorepo share the same top-level namespace, they collide when installed in the same environment. This hook can rewrite imports during packaging to add a custom namespace wrapper, preventing those collisions.

The rewriting uses Python's ast module to parse and modify source code, injecting a custom top namespace into all imports. Without a custom namespace configured, the hook simply includes bricks as-is. It's designed for teams using Polylith who need to publish multiple independent libraries from a single workspace without namespace conflicts.

Use it for:

- Publishing multiple Python libraries from a Polylith monorepo without namespace collisions when installed together.
- Automatically including Polylith bricks in wheel and sdist distributions during Hatch builds.
- Adding a custom namespace prefix to library code during packaging to isolate it from other monorepo libraries.
- Simplifying build configuration for Polylith workspaces by automating brick discovery and inclusion.
- Rewriting internal imports in source code to reflect a different namespace structure in the published package.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Hatch build hook that integrates Polylith architecture bricks into Python packages and optionally rewrites imports to add a custom namespace during packaging.

Yes, if you are using Hatch as your build backend and Polylith as your monorepo architecture. The hook solves the specific problem of packaging multiple libraries from one workspace without namespace conflicts. Install friction is low, maintenance is active, and there are no known vulnerabilities. Not relevant if you are not using Polylith or a different build system.

## Install

pip install hatch-polylith-bricks
uv add hatch-polylith-bricks
poetry add hatch-polylith-bricks

## Installing hatch-polylith-bricks

Before you install: Low friction: pure Python wheel with only two lightweight runtime dependencies (hatchling and tomlkit). Active maintenance with a recent release 42 days ago and no security vulnerabilities.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

Add to pyproject.toml:

[build-system]
requires = ["hatchling", "hatch-polylith-bricks"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.polylith-bricks]
# Section enables the hook

[tool.polylith.bricks]
"../../bases/my_namespace/my_base" = "my_namespace/my_base"

Then run: hatch build

Requires Hatch as your build backend and a Polylith workspace structure with bricks in bases/ and components/ directories.

Verify before relying:

- Whether AST-based import rewriting handles all Python import patterns (relative imports, star imports, etc.)
- Performance impact when rewriting large codebases with many bricks
- Compatibility with Polylith workspaces using non-standard directory layouts

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 299.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

hatch build hook polylith, polylith bricks packaging, monorepo namespace collision, hatch plugin architecture, python polylith integration, custom namespace packaging, polylith workspace build, monorepo, polylith-architecture, hatch-plugin

[View on SkillFed](https://skillfed.io/packages/hatch-polylith-bricks) · [View on PyPI](https://pypi.org/project/hatch-polylith-bricks/)