Polylith CLI

1.45.0 · active · verified Fri Apr 17

The `polylith-cli` is a command-line interface tool that provides essential tooling support for developing Python applications using the Polylith Architecture. It helps manage workspaces, create bases and components, and analyze dependencies within a monorepo structure. As of version 1.45.0, it is actively developed with regular updates and new features.

Common errors

```
Error: A brick named 'my_component' already exists. Aborting.
```
cause Attempting to create a component or base with a name that is already in use within the workspace.

fix Choose a unique name for your new component/base, or delete the existing one if no longer needed. Check existing bricks with `poly info`.
```
ModuleNotFoundError: No module named 'typing_extensions'
```
cause Missing `typing_extensions` dependency, particularly on Python 3.8, due to `typer` updates.

fix Update `polylith-cli` to the latest version (`pip install --upgrade polylith-cli`). If the problem persists, manually install `typing-extensions`: `pip install typing-extensions`.
```
ModuleNotFoundError: No module named 'polylith_cli'
```
cause Trying to import the `polylith_cli` package in Python code. This package is designed to provide the `poly` command-line entry point, not for direct programmatic import by end-users.

fix Use the `poly` command in your terminal instead of attempting to import it in Python code. For example, run `poly info` from your command line.
```
poly check failed. Missing dependency 'my_third_party_lib' in project 'my_project' (found import in 'my_component')
```
cause Older versions of `poly check` could incorrectly report missing dependencies when a third-party library's name was similar to a Polylith top-level namespace.

fix Upgrade `polylith-cli` to version 1.42.0 or higher (`stable-99` or newer). If the issue persists with the latest version, verify `my_third_party_lib` is correctly listed in your project's `pyproject.toml` or `requirements.txt`.

Warnings

gotcha Polylith CLI is primarily a command-line tool. It is not designed for direct Python import into user applications. Its functionality is accessed via the `poly` executable.
Fix: Interact with `polylith-cli` via your terminal using the `poly` command, e.g., `poly info` or `poly check`.
breaking The `poly create component` and `poly create base` commands now validate brick names and will exit with a failure code if a brick with the same name already exists in the workspace.
Fix: Ensure brick names are unique before attempting to create them. Use `poly info` to see existing bricks.
gotcha `poly check` and `poly libs` might have previously incorrectly reported missing imports/dependencies for third-party libraries sharing similar top-level namespaces with Polylith bricks. This was fixed in `stable-99`.
Fix: Update `polylith-cli` to version 1.42.0 or higher to ensure accurate dependency checking.
gotcha Python 3.8 users encountered `ModuleNotFoundError: No module named 'typing_extensions'` due to a missing dependency. This was patched in `stable-94`.
Fix: Ensure `polylith-cli` is updated to version 1.37.0 or higher. If issues persist, manually install `typing-extensions` via `pip install typing-extensions`.

Install

pip install polylith-cli Install latest version

Quickstart

Start by creating a new Polylith workspace, then generate components and use `poly info` to inspect the structure.

# Create a new Polylith workspace
poly create workspace my_polylith_project

# Navigate into the workspace
cd my_polylith_project

# Create a new component
poly create component my_component

# Get information about the workspace
poly info

view raw JSON →