Skip to content

Migrating to Polylith

If you decide to give Polylith a try with existing code, the suggestion is to:

  • create a new repo and workspace. See setup and commands.
  • choose one of your existing services or apps to migrate into the newly created Polylith repo.
  • create a base with the poly tool and put all of the existing Python code in there. Don't worry, we will fix this in next steps.
  • create a new project with the poly tool - this will be the project infrastructure for the service or app that currently lives in the base you added in the prevous step.

The entrypoint for your app would be something like:


packages = [
    {include = "your_namespace/your_app", from = "../../bases"}

# insert the needed 3rd party libraries here

Hatch, PDM and Rye

dependencies = [] # insert the needed 3rd party libraries here

"../../bases/your_namespace/your_app" = "your_namespace/your_app"

You should now be able to run the service or app locally.

Next step: migrating code to bricks

Now you are ready for the actual migration: identifying parts of the source code that could be grouped into what Polylith refers to as components. Moving them - one by one - out of the base and into new components. Add the components to the pyproject.toml according to the example in Projects & pyproject.toml.

When is the migration finished?

The base would ideally contain the entry point, and import all the needed components. You can test out the service or app, run the info, libs and check commands to verify all things are in place. See commands.

Continue with your next existing service or app! By now, you should already be able to share components between your services.

Migrating away from Polylith?

This step is simple.


poetry build-project --directory path/to/project


cd path/to/project

hatch build


cd path/to/project

pdm build


cd path/to_project

rye build --sdist

The output is a wheel and, more importantly, an sdist (a source distribution). It is essentially a zip file containing all source code used in the project.

That's all!