Add existing projects to a new workspace: PyCharm 2026.3 Workspace mode

Background/Situation

PyCharm 2026.3 has Workspace mode, and it is on by default. In Workspace mode, every folder with a pyproject.toml file is a separate Python project. PyCharm reads these files and sets up the projects and the dependencies between them. When a pyproject.toml file or a project folder changes, PyCharm updates the setup.

Question

How to put several existing Python projects into a new workspace and open all of them in one PyCharm window?

Answer

A workspace is a folder that holds the project folders.

1. Create a new empty folder for the workspace, for example my-workspace
2. Move the folders of the existing projects into the new folder
3. Open the new folder in PyCharm with File | Open

PyCharm creates a separate project for each folder with a pyproject.toml file. The workspace folder needs no pyproject.toml file of its own. An old .idea folder inside a project folder can stay: PyCharm keeps the workspace setup in the .idea folder of the workspace folder.

By default, each project gets its own environment. When a file of a project without an environment is opened, the editor shows the notification No Python interpreter configured for project-a. The notification has two buttons: Set up uv environment and Custom environment. Set up uv environment creates a .venv folder in that project folder.

The PyCharm help describes these features in Workspaces and monorepos, Create and manage subprojects and Configure a uv environment.

A project folder without pyproject.toml

In the Project tool window, right-click the folder. Select Convert to Project with uv. PyCharm creates the project in that folder and keeps the existing files. The menu item names the package manager of the surrounding project's interpreter, so it can also read Convert to Project with Poetry, Hatch or pip.

A new project in the workspace

In the Project tool window, right-click a folder. Select New | New Project with uv. The menu item is available only when the surrounding project has a pyproject.toml file. Inside a uv workspace, uv adds the new project to the members list of the root pyproject.toml file.

One shared uv environment for all projects

In a uv workspace, all projects share one virtual environment. To set one up, add a pyproject.toml file to the workspace folder and list the project folders in members:

[tool.uv.workspace]
members = ["project-a", "project-b"]

Then open a file of any project. Click Set up uv environment in the notification. PyCharm creates one .venv folder and one uv.lock file in the workspace folder, and every project of the workspace uses this environment.

Projects of a Poetry or Hatch monorepo keep a separate environment each.

Attach Project

In Workspace mode, the Attach option has a known bug. A project attached to an open project disappears after PyCharm rebuilds the project model from pyproject.toml (PY-90864). The folder setup above does not use Attach.