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.
Workspace mode
Workspace mode is enabled by default. When you open a project that contains pyproject.toml files, PyCharm derives the workspace structure and dependencies from these files automatically.
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.
Project model updates
PyCharm keeps the project model in sync with the pyproject.toml files automatically. When you create, change, or delete a pyproject.toml file, or add or remove a directory in the workspace, PyCharm rebuilds the project model.
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.
If the root pyproject.toml declares subpackages using the [tool.poetry] packages table, for example:
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 suggests 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 suggests adding the package to the environment and updating the corresponding .toml file.
Dependency insights in configuration files
PyCharm provides inline information about dependencies declared in pyproject.toml and requirements.txt files, so you can review package details without leaving the editor.
Inline version hints
Next to each requirement definition in pyproject.toml or requirements.txt, PyCharm shows the exact installed version of the package as a gray inline hint.
Quick documentation
To view information about a package, including its current version, license, and upstream repository links, hover over the package name or place the caret at it and press Ctrl+Q.
Navigate to dependencies
Hold Ctrl and click a package name to open its specification in an editor tab. For internal workspace dependencies, the same action opens the source module in the Project tool window.
Django and FastAPI in workspaces
Django
PyCharm enables Django support separately for each workspace project that contains a manage.py file. The folder with manage.py becomes the Django project root, and PyCharm creates a Django server run/debug configuration for this project.
Code completion and navigation use the Django settings, applications, models, and templates of the current project and the projects that it depends on. Projects that have applications with the same names do not interfere with each other.
To configure Django for a project, open the Django settings () and select the project in the list.
When you run a manage.py task, PyCharm uses the project of the selected file. If this project does not use Django, PyCharm uses the only Django project of the workspace or asks you to choose one.
FastAPI
A FastAPI run/debug configuration belongs to a workspace project. If you leave the Working directory field empty, PyCharm runs the application in the folder of this project.
Troubleshooting
PyCharm tries to make environment configuration for subprojects simple and allow the IDE to handle it automatically. However, if something does not work as expected, you can track the commands executed in the backend and analyze their output in the Process Output tool window.