工作区和多项目仓库

大型项目可以拆分为较小的部分(如后端、API 和共享代码)，使其更易于组织和维护。 PyCharm 支持使用此类多项目 Python 结构，包括 uv 工作区和基于路径的依赖（uv、Poetry 和 Hatch）。

启用工作区模式后，包含 pyproject.toml 的目录将成为托管的 Python 项目。 PyCharm 会自动检测工作区成员和子项目，配置环境并管理它们之间的依赖。

启用工作区模式

工作区模式默认启用。打开包含 pyproject.toml 文件的项目时，PyCharm 会自动从这些文件中派生工作区结构和依赖项。

在设置中切换 Workspace 模式。

在设置对话框（Ctrl+Alt+S ），转到项目结构。
选中或清除使用基于 pyproject.toml 的项目模型[测试版] 复选框。

工作空间结构

项目检测

包含 pyproject.toml 的目录将成为托管的 Python 项目。 PyCharm 会读取工作区配置并自动检测所有项目。

项目命名

每个项目名称根据其 [project] name 字段在 pyproject.toml 文件中派生。如果缺少该字段，则使用目录名。

IDE 中的项目名称必须唯一。当多个 pyproject.toml 文件解析为相同名称时，IDE 会附加 @N 后缀（从 @1 开始）以区分它们。为避免此情况，请确保工作区内每个 pyproject.toml 声明唯一的 [project] name。

依赖项

项目间的依赖将从 pyproject.toml 声明中自动解析。依赖关系会以只读方式在文件 | 设置 | 项目| 项目依赖项中可视化展示。如需更改，请手动编辑 pyproject.toml 文件。

项目结构存储在 .iml 文件的 .idea 目录下，并在每次同步时根据 pyproject.toml 生成。

设置工作区

根据所使用的工具，工作区可以如下组织：

uv 工作区

uv 工作区使用所有项目共享的单个虚拟环境。在根 pyproject.toml 中定义工作区成员，并将其作为工作区依赖进行引用：

                [tool.uv.workspace]
                members = ["packages/*"]

                [project]
                dependencies = ["my-lib"]

                [tool.uv.sources]
                my-lib = { workspace = true }
            
   

Poetry 和 Hatch 多项目仓库

在 Poetry 和 Hatch 多项目仓库中，每个项目独立配置并拥有自己的环境。

PyCharm 会自动检测目录结构中的子项目，并为每个项目配置环境。

如果根 pyproject.toml 使用 [tool.poetry] packages 表声明了子包，例如：

                [tool.poetry]
                packages = [
                    { include = "pkg_a", from = "packages" },
                    { include = "pkg_b", from = "packages" }
                ]
            
   

自动环境配置

当在工作区成员或子项目中打开 .py 或 pyproject.toml 文件后，PyCharm 会检查系统上是否已经存在该项目的环境：

如果存在环境，会自动将其设置为 SDK。
如果不存在环境，会出现文件级通知，建议为该项目创建新环境并安装依赖。

建议的工具由在 pyproject.toml 中指定的构建工具决定，如果有的话。如果未指定工具，PyCharm 会建议使用 uv （如果已安装）或 venv。

环境一致性

PyCharm 会验证环境一致性，并在 pyproject.toml 中定义的依赖缺失时发出警告。将提供快速修复以安装缺失的依赖。

如代码中导入了某个包，但未在工作区成员的 pyproject.toml 中列出，快速修复将建议将该包添加到环境并更新对应的 .toml 文件。

配置文件中的依赖洞察

PyCharm 会在 pyproject.toml 和 requirements.txt 文件中声明的依赖项旁提供内联信息，让你无需离开编辑器即可查看软件包详情。

内联版本提示

在 pyproject.toml 或 requirements.txt 中每个依赖定义旁，PyCharm 会以灰色内联提示显示该软件包的确切已安装版本。

快速文档

要查看关于软件包的信息，包括其当前版本、许可证和上游仓库链接，将鼠标悬停在软件包名称上，或将文本光标放在其上并按 Ctrl+Q。

导航到依赖项

按住 Ctrl 并点击软件包名称，可以在编辑器标签页中打开其规范。对于内部工作区依赖项，执行相同操作可在项目工具窗口中打开源模块。

同步项目

可以使用使用 pyproject.toml 同步项目操作，将项目模型与 pyproject.toml 文件手动同步。这会基于当前 pyproject.toml 文件状态重建项目模型。

故障排除

PyCharm 力图简化对子项目的环境配置，并让 IDE 自动处理。但如果没有如预期运行，可以通过跟踪后台执行的命令，并在 Process Output 工具窗口中分析其输出。

2026年 7月 14日