PyCharm 2026.3 Help

Python 工具支持

PyCharm 支持多种工具,以提高代码质量、可维护性和工作流程效率:

  • Ruff :一种高性能的代码检查器和格式化器,可检测错误并强制执行编码规范。

  • Pyright、 basedpyright、 Pyrefly 和 ty :提供实时类型分析的快速类型检查器。

  • Black :一种自动代码格式化器,有助于保持一致的风格。

打开 Python 文件时,活动的 LSP 工具会显示在底部工具栏中:

在工具栏中显示的 Python LSP 工具

如果在项目环境中检测到 Python 工具,PyCharm 会显示一条通知,建议启用该工具。 点击通知即可无需打开设置直接启用该工具。

外部工具设置页面

所有支持的外部工具都在一个页面上配置: Python | 工具 | 外部工具。 该页面显示了 PyCharm 当前支持的所有工具(linter、类型检查器、格式化程序)的表格。

对于每个工具,表格显示同一组控件:

  • 开/关切换 用于启用或禁用工具集成。

  • 查找 列显示 PyCharm 如何定位工具可执行文件。 PyCharm 会按以下顺序尝试来源,并使用找到该工具的第一个来源:

    1. 环境 :安装在项目环境中的工具软件包。 如果项目有多个环境, 环境 还会显示其中有多少个环境包含该工具,例如 环境 (1/3)。

    2. 路径 :系统 $PATH 中可用的可执行文件,或您提供的显式路径。

    3. uvx :PyCharm 通过 uv 运行工具,而无需将其安装到环境中。

    PyCharm 使用的来源以粗体显示。 如果在任何来源中都找不到已启用的工具,整个查找链会以红色显示。

  • 工具配置的其他设置。

    要打开其他设置,请点击工具名称旁边的 尖括号图标 ,或点击工具所在行。

  • 一个按工具划分的 功能 列表,可在其中选择该工具应在编辑器中提供哪些功能(例如检查、补全、嵌入提示、格式设置或导入优化)。 可用功能列表取决于工具。

  • 环境 部分会列出每个项目环境及其路径和工具版本。 如果该工具未安装在某个环境中,环境名称旁边会显示 未安装 和 安装 链接。 点击 安装 将工具安装到此环境中。

  • 路径 行会显示可执行文件的路径及其版本。 要选择其他可执行文件,请点击 浏览可执行文件图标 (浏览可执行文件)。

    根据工具的状态,路径旁边会显示以下链接之一:

    • 安装 :安装该工具并全局使用。

    • 升级 :将工具升级到较新版本。

    • 使用自动检测 :丢弃手动选择的可执行文件,并自动检测工具。

basedpyright 静态类型检查工具,基于 pyright。

basedpyright 是 Pyright 的一个分支,包含多项类型检查改进。

您可以启用以下 basedpyright 选项:

将新错误写入基线文件。

基线 是一种保存当前类型检查错误集合的方法,可帮助你在逐步提升类型覆盖的同时,防止新增错误被引入。

在 PyCharm 中使用基线:

  1. 启用 basedpyright。

  2. 在你的项目中打开包含 basedpyright 类型检查错误的文件。

  3. 转到 帮助 | 查找操作 (或按 Ctrl+Shift+A ),搜索 basedpyright:将新错误写入基线 并选中它。

    basedpyright 会创建一个 baseline.json 文件,存放在 .basedpyright 目录中。 它会忽略此文件中列出的错误,并继续报告新的类型错误。

Black

您可以在 PyCharm 中使用 Black 格式化您的 Python 代码。

可以在 pyproject.toml 文件中配置 Black 格式化器的设置。 有关详细信息,请参阅 Black 文档。

还可以使用 参数 字段指定其他选项,或覆盖 pyproject.toml 中的设置。

有关详细信息,请参阅 Black CLI 参考。

Pyrefly

Pyrefly 是适用于 Python 的类型检查器和语言服务器。

您可以启用以下 Pyrefly 选项:

Pyright 静态类型检查器工具集包。用于 Python 代码的类型分析、查错和补全。

Pyright 是 Python 的静态类型检查器。

您可以启用以下 Pyright 选项:

Ruff

Ruff 可以在您输入时高亮问题、建议修复,并帮助在整个项目中保持一致的代码质量。 其运行速度快,并可直接在编辑器中提供实时反馈。

PyCharm 对 Ruff 的支持包括:

  • 格式化

  • 导入优化

  • 快速修复

  • 配置文件验证

  • 规则代码的内联提示

    查看规则代码的嵌入提示
  • 规则代码和配置选项的补全

    使用自动补全
  • 规则代码和配置选项的 Web 链接

    按下 Ctrl (在 macOS 上为 ⌘ )并点击规则代码或配置选项,即可在 Ruff 文档 中打开其页面。

  • 规则代码和配置选项的编辑器内文档预览

    在编辑器中预览文档

您可以启用以下 Ruff 选项:

  • 检查

  • 格式化

  • 格式化时对导入进行排序 :如果启用了 格式化 ,Ruff 在重新格式化整个文件时也会对导入进行排序。 它不会移除未使用的导入。

  • 导入优化器

  • 在保存时运行代码修复 :保存 Python 文件时,Ruff 会针对项目中已启用的规则应用其 安全修复。

将 Ruff 修复应用于作用域

可以一次性将 Ruff 的安全修复应用于项目、模块、目录或自定义作用域中的所有 Python 文件。

  1. 在 外部工具设置页面 上启用 Ruff。

  2. 在主菜单中,转到 代码 | 应用 Ruff 修复。

  3. 在打开的对话框中,选择作用域并点击 分析。

    Ruff 会针对项目中已启用的规则,将其安全修复应用于作用域内的 Python 文件。 要还原所有更改,请按 Ctrl+Z。

ty

ty 是一个快速的 Python 类型检查器,使用 Rust 编写。 当前为预览版,功能可能不完整。

您可以启用以下 ty 选项:

2026年 11月 3日