Workspaces and monorepos
A large project can be split into smaller parts (like backend, API, and shared code), making it easier to organize and maintain. PyCharm supports working with such multi-project Python setups, including uv workspaces and path-based dependencies (uv, Poetry, and Hatch).
When Workspace mode is enabled, directories containing pyproject.toml become managed Python projects. PyCharm automatically detects workspace members and subprojects, configures environments, and manages dependencies between them.
Enable workspace mode
When you open a project that contains pyproject.toml files, PyCharm may show a notification titled pyproject.toml workspace detected, suggesting enabling the Workspace mode.
You can click Enable to turn on Workspace mode, or Don't show again to dismiss the notification.
If you enable the Workspace mode, PyCharm will derive workspace structure and dependencies from pyproject.toml files.
Enable Workspace mode in the settings
In the Settings dialog (Ctrl+Alt+S) , go to .
Select the Use pyproject.toml-based project model [beta] checkbox.
Workspace structure
Project detection
Directories containing pyproject.toml become managed Python projects. PyCharm reads the workspace configuration and detects all projects automatically.
Project naming
Each project name is derived from the [project] name field in its pyproject.toml file. If the field is missing, the directory name is used instead.
Project names in the IDE must be unique. When multiple pyproject.toml files resolve to the same name, the IDE appends an @N suffix (starting from @1) to disambiguate them. To avoid this, ensure each pyproject.toml in the workspace declares a distinct [project] name.
Dependencies
Dependencies between projects are resolved automatically from pyproject.toml declarations. The dependencies are visually presented in as read-only. To make changes, edit the pyproject.toml file manually.
Project structure is stored in .iml files inside the .idea directory and is generated from pyproject.toml on each sync.
Set up a workspace
Depending on the tool you use, workspaces can be organized in the following ways:
uv workspaces
uv workspaces use a single virtual environment shared across all projects. Define workspace members in the root pyproject.toml and reference them as workspace dependencies:
Poetry and Hatch monorepos
In Poetry and Hatch monorepos, each project is configured independently and has its own environment.
PyCharm automatically detects subprojects in a directory structure and configures an environment for each project.
Automatic environment configuration
Once a .py or pyproject.toml file is opened in a workspace member or subproject, PyCharm checks whether an environment for this project already exists on the system:
If an environment exists, it is automatically set as the SDK.
If no environment exists, a file-level notification suggests creating a new environment and installing dependencies for this project.
The suggested tool is determined by the build tool specified in pyproject.toml, if any. If no tool is specified, PyCharm will suggest using uv (if it is installed on the system) or venv.
Environment consistency
PyCharm verifies environment consistency and warns you if a dependency defined in pyproject.toml is missing from the environment. A quick-fix is provided to install the missing dependency.
If a package is imported in your code but not listed in the workspace member's pyproject.toml, a quick fix will suggest adding the package to the environment and updating the corresponding .toml file.
Syncing the project
You can manually sync your project model with the pyproject.toml files by using the Sync Project with pyproject.toml action. This rebuilds the project model based on the current state of your pyproject.toml files.
Troubleshooting
PyCharm tries to make environment configuration for subprojects simple and allow the IDE to handle it automatically. However, if something doesn't work as expected, you can track the commands executed in the backend and analyze their output in the Process Output tool window.