Submodules as one project

[u/lonelypenguin20]

Working in Pycharm. I have a repo that includes a bunch of submodules. For a long time, PyCharm interpreted it as one big project: marking directories as sources meant that ctrl+lmb will send me into the submodule code even from other submodules, and they all shared the same python env.

currently, after an update several months ago, this is not the case: each submodule requires setting up the interpreter separately, and marking a directory as a submodule does nothing for code in other submodules - ctrl + lmb sends to the installed module (if I have configured the env/interpreter, that is)

Is there a way to change this behavior? A setting somewhere? It slows me down a lot =\

PS one workaround seems to disable pyproject.toml-based project structure, and then to manually add extra "content root" to every module that has dependencies on others, but that seems... pretty laborous

[u/PyJet]

Ctrl+click = Go to Declaration, and where it lands depends on whether PyCharm has a module dependency edge between your submodules.

Since 2026.2 the project structure is derived from pyproject.toml rather than from manually marked source roots. Each pyproject.toml becomes its own module, and the edges between modules come from what those files declare. Your submodules don't reference each other, so there are no edges — hence the separate interpreters and Ctrl+click landing in site-packages.

This is deliberate, and it's going further: from 2026.3 the pyproject.toml files become the single source of truth for project structure — setting module dependencies manually in Project Structure is going away, along with the per-project toggle for the old behaviour. So the setup worth investing in is declaring the relationships in the toml files.

For your case a uv workspace fits: one pyproject.toml at your repo root listing the submodules as members, and each submodule declaring the siblings it actually uses as dependencies. That gives you a single shared venv for all members, plus Ctrl+click into sibling sources. Docs: https://docs.astral.sh/uv/concepts/projects/workspaces/

One thing that trips people up: membership and dependencies are separate. Listing a submodule as a workspace member gives you the shared interpreter; only declaring it as a dependency ([tool.uv.sources] sub-b = { workspace = true }) makes Ctrl+click follow into it.

If some submodules aren't really part of one project, declare the link directly instead of using workspace membership — in the depending project's pyproject.toml:

[project]

dependencies = ["sub-b @ file:///abs/path/to/sub-b"]

That's standard PEP 621, so it works whatever tool you use — no uv needed. Ctrl+click follows it into the sibling's sources exactly as with a workspace dependency; the difference is each project keeps its own interpreter. With uv you can also write it relative as [tool.uv.sources] sub-b = { path = "../sub-b" }.

The target directory has to be inside the opened project and have its own pyproject.toml, otherwise there's nothing to link to.

PS — there's a global registry flag that disables pyproject.toml discovery entirely, and that one is staying: Help | Find Action → "Registry", set intellij.python.pyproject.model to off, restart. It's application-level, so it affects every project you open.

[u/skroll]

Are you using uv? If so, are you using workspaces?

https://docs.astral.sh/uv/concepts/projects/workspaces/

These have been working great inside of PyCharm for me.

[u/lonelypenguin20 → u/skroll]

nope, good old pypi

also I think I figured it out. I didabled pyproject based structure and deleted content root from every package