Setup

Create a Polylith Workspace

Create a directory for your code, initialize it with git and create a basic Poetry, Hatch or PDM setup:

git init

Poetry

poetry init

From the Poetry docs:

This command will help you create a pyproject.toml file interactively by prompting you to provide basic information about your package. It will interactively ask you to fill in the fields, while using some smart defaults.

Create a workspace, with a basic Polylith folder structure.

poetry poly create workspace --name my_namespace --theme loose

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

Create a virtual environment for the workspace.

poetry install

Hatch

hatch new --init

From the Hatch docs:

Create or initialize a project.

Note: using --init to avoid creating any boilerplate code.

Add the Polylith CLI as a dev dependency, and configuration for the virtual environment in the pyproject.toml file:

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

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

Create a Hatch virtual environment:

hatch env create

Create a workspace, with a basic Polylith folder structure.

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

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

PDM

pdm init -n --backend pdm-backend minimal

From the PDM docs

Initialize with the builtin "minimal" template, that only generates a pyproject.toml.

and PDM init

Specify the build backend, which implies --dist

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

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

Rye

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

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

Edit the configuration

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

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

Remove the [tool.hatch.build.targets.wheel] section.

Run the sync command to update the virtual environment:

rye sync

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

rm -r src

uv

uv init my_repo  # name your repo

cd my_repo

uv add polylith-cli --dev

uv sync  # create a virtual environment and lock files

as an alternative to adding a dev dependency, it is also possible to use uvx (example usage: uvx --from polylith-cli poly info).

Create a workspace, with a basic Polylith folder structure.

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

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

Edit the project configuration

The recommended build backend for uv is Hatch. This is because of the very useful build hook support. Make sure to add this section, if not already added, in the pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Make uv 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:

uv sync

What about the uv Build Backend?

You can use the uv build backend with Polylith, even if the hatch backend is the recommended one.

Add this configuration, to make uv aware of namespace packages and the top namespace.

[tool.uv.build-backend]
namespace = true
module-name = "<the polylith top namespace here>"
module-root = ""

Maturin

Add the polylith-cli as a development dependency to your pyproject.toml file:

[project.optional-dependencies]
dev = [
    "polylith-cli",
]

python -m venv .venv
pip install

source .venv/bin/activate

Create the Polylith Workspace

Create a workspace, with a basic Polylith folder structure.

poly create workspace --name my_namespace --theme loose

Edit the configuration

Make Maturin aware of the way Polylith organizes source code by adding this to the pyproject.toml:

[tool.maturin]
include = ["bases", "components", "development", "."]

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace, loose is the recommended structure for Python.

Pixi

Have a look at the Pixi docs for initializing a new repo or project. For the Polylith initial setup, look at the Hatch sections at this page.

Pantsbuild (aka Pants)

Have a look in the Pants-specific example repository for details on the setup. You will find examples of combining Pants with Polylith, by using the Hatch build backend in the project-specific configurations.

Next steps

You now have the repo structured as a Polylith Workspace. Great! Add Python code to the Workspace by creating bases and components. The common name is bricks (like LEGO bricks). There's more about the Workspace and the bricks in the Polylith Workspace section.

The Polylith tool includes commands to create bases and components. You will find documentation about commands in the Commands section.

Example (using uv):

# create a base
uv run poly create base --name my_base

# create a component
uv run poly create component --name my_component