Setup
Create a Polylith Workspace
Create a directory for your code, initialize it with git and create a basic Poetry, Hatch or PDM setup:
Poetry
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.
--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.
Hatch
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:
Create a workspace, with a basic Polylith folder structure.
--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
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).
Add the polylith-cli
Add the Polylith CLI as a dev dependency and setup the virtual environment paths.
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.
--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.
--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:
Remove the [tool.hatch.build.targets.wheel]
section.
Run the sync
command to update the virtual environment:
Finally, remove the src
boilerplate code that was added by Rye in the first step:
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
Create a workspace, with a basic Polylith folder structure.
--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
Make sure that the build backend for uv is set to Hatch.
Make uv (and Hatch) aware of the way Polylith organizes source code:
Run the sync
command to update the virtual environment:
Finally, remove the src
boilerplate code that was added by uv in the first step:
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):