Python tooling for Polylith

A command line interface that adds tooling support for the Polylith Architecture in Python.

Documentation

Have a look at the documentation. You will find installation, setup, usage guides and more.

Quick start

Poetry user? For Poetry, the recommended setup is to install the poetry-polylith-plugin. Read more about Poetry in the documentation.

Setup for Hatch users

Create a directory for your code, initialize it with git and setup the basics with hatch:

git init

hatch new --init

Add the Polylith CLI as a dev dependency in pyproject.toml:

[tool.hatch.envs.default]
dependencies = ["polylith-cli"]

Add configuration for a local virtual environment in the pyproject.toml:

[tool.hatch.envs.default]
type = "virtual"
path = ".venv"
python = "3.12"  # your preferred version here

Make Hatch aware of the Polylith structure, by adding this to the pyproject.toml:

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Next: create a Polylith workspace, with a basic Polylith folder structure. The poly command is now available in the local virtual environment. You can run commands in the context of hatch run to make Polylith aware of the development environment.

hatch run poly create workspace --name my_namespace --theme loose

Ready for coding!

Add components, bases and projects:

hatch run poly create component --name my_component

hatch run poly create base --name my_example_endpoint

hatch run poly create project --name my_example_project

For details, have a look at the documentation. There, you will find guides for setup, migration, packaging, available commands, code examples and more.

Setup for PDM users

Create a directory for your code, initialize it with git and setup the basics with PDM.

git init

pdm init -n --backend pdm-backend minimal

Add a workspace hook

Make PDM aware of the Polylith structure, by adding the pdm-polylith-workspace hook to the newly created pyproject.toml.

The build hook will add an additional pth file to the virtual environment, with paths to the Polylith source code folders (bases, components).

[build-system]
requires = ["pdm-backend", "pdm-polylith-workspace"]
build-backend = "pdm.backend"

Add the polylith-cli

Add the Polylith CLI as a dev dependency and setup the virtual environment paths.

touch README.md

pdm add -d polylith-cli

pdm install

Next: create a Polylith workspace, with a basic Polylith folder structure. The poly command is now available in the local virtual environment. You can run commands in the context of pdm run to make Polylith aware of the development environment.

pdm run poly create workspace --name my_namespace --theme loose

Ready for coding!

Add components, bases and projects:

pdm run poly create component --name my_component

pdm run poly create base --name my_example_endpoint

pdm run poly create project --name my_example_project

Setup for Rye users

rye init my_repo  # name your repo

cd my_repo

rye add polylith-cli --dev

rye sync  # create a virtual environment and lock files

Create a workspace, with a basic Polylith folder structure.

rye run poly create workspace --name my_namespace --theme loose

Setup for uv users

uv init -name my_repo  # name your repo

cd my_repo

uv add polylith-cli --dev

uv sync  # create a virtual environment and lock files

Create a workspace, with a basic Polylith folder structure.

uv run poly create workspace --name my_namespace --theme loose

Rye and uv users: edit the configuration

The default build backend for Rye and uv is Hatch. Make Rye and uv (and Hatch) aware of the way Polylith organizes source code:

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Run the sync command to update the virtual environment:

Rye:

rye sync

uv:

uv sync

Finally, remove the src boilerplate code that was added by Rye and uv in the first step:

rm -r src

Rye and uv users: ready for coding!

Add components, bases and projects:

Rye:

rye run poly create component --name my_component

rye run poly create base --name my_example_endpoint

rye run poly create project --name my_example_project

uv:

uv run poly create component --name my_component

uv run poly create base --name my_example_endpoint

uv run poly create project --name my_example_project

For details, have a look at the documentation. There, you will find guides for setup, migration, packaging, available commands, code examples and more.

Release files for polylith-cli 1.50.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polylith-cli 1.50.0
File	Size	Uploaded
polylith_cli-1.50.0.tar.gz	100.3 kB	Aug 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for polylith-cli 1.50.0
File	Interpreter	ABI	Platform	Reset
polylith_cli-1.50.0-py3-none-any.whl 170.6 kB Aug 7, 2026	Python 3	none	any	Details

Total release size: 270.9 kB

Release files / polylith_cli-1.50.0.tar.gz

Download URL	polylith_cli-1.50.0.tar.gz
Size	100.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`5d5af88abbe6b5f48b1aff10bb0144c7ecf67571cbcd2e1ff44ca9204004cbd5`
BLAKE2b-256 checksum How to use checksums	`247f1364091fcb5555606ad6db6900770974ccc61ad419f0464049392758439e`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.1`

Release files / polylith_cli-1.50.0-py3-none-any.whl

Download URL	polylith_cli-1.50.0-py3-none-any.whl
Size	170.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`37b5beb8afed42cf07cd3d0fc7679cb53297de2c71a297f55f5e771ba73b621c`
BLAKE2b-256 checksum How to use checksums	`7ea4b12a493d37f2fed8eafe5cd2ad696f2cbd2277bc93297928aebd877928f3`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.1`