Create and manage subprojects

A large project can be split into smaller parts, such as a backend, an API, and shared code. Each part can be configured as a separate subproject with its own pyproject.toml file.

PyCharm uses the pyproject.toml files in the project directory structure to detect and configure subprojects.

You can create a new subproject with uv, Poetry, Hatch, or pip, or convert an existing directory into a subproject.

Create a subproject

The action is available only when the project has a pyproject.toml file.

In the Project tool window, right-click the directory where you want to create the subproject, or select the directory and click the button on the tool window toolbar.
Select New | New Project with <tool>. The tool is the package manager of the interpreter of the module that contains the directory: uv, Poetry, Hatch, or pip.
In the dialog that opens, specify the subproject name and click OK.
With uv, PyCharm runs uv init <name> in the directory. If the directory is inside a uv workspace, uv adds the new project to members in the root pyproject.toml file.

Convert a directory to a subproject

You can convert an existing directory into a subproject. The action is not available if the directory already contains a pyproject.toml file. PyCharm uses the package manager of the interpreter of the module that contains the directory.

In the Project tool window, right-click the directory that you want to convert.
Select Convert to Project with <tool>.
PyCharm initializes a subproject in the selected directory and keeps the existing files.

To open a Python console that runs on the interpreter of a subproject, right-click the subproject in the Project tool window and select Open In | Python Console. For more information, refer to Open a Python console for a subproject.

02 November 2026