PyCharm 2025.2 Help

PyCharm 故障排除

在使用 PyCharm 时，您可能会遇到一些警告或错误消息。 本章提供了已知问题的解决方案和解决方法列表。

您还可以找到有关故障排除和执行工作环境基本诊断的建议。

已报告的问题

可能的原因

解决方案

项目设置

在 首选项/设置 | 项目 | Python 解释器 中的可用解释器列表中，一个 Python 解释器被标记为不受支持。

标记的解释器的 Python 版本已过时，且在 PyCharm 中不受支持。

您可以从可用解释器列表中删除不受支持的解释器。 有关支持的 Python 版本的更多信息，请参阅 Python 支持。

代码编辑

PyCharm 编辑器限制了代码编辑。

您已安装 IdeaVim 插件，因此启用了 vim 编辑模式。

在 工具 菜单中取消选择 Vim 模拟器。 有关更多详细信息，请参阅 在 PyCharm 中使用 Vim 编辑器仿真。

Python 代码在编辑器中未高亮显示。

PY 文件被关联为文本文件格式。

在 设置 对话框（Ctrl+Alt+S ）中，导航到 编辑器｜文件类型 ，从 已识别的文件类型 列表中选择 文本 ，从 文件名模式 列表中选择 *.py ，然后点击 移除。

代码补全

代码补全操作不可用。

省电模式 已启用。

从主菜单中选择 文件 并取消选中 节能模式 复选框。

您的文件不在内容根中，因此无法获得代码补全所需的类定义和资源。

重新组织您的源文件。

包含您希望出现在补全建议列表中的类和函数的文件是纯文本文件。

重新考虑并修改（如有必要）您的源文件格式。

调试

无法调试 Docker 运行/调试配置； 调试 操作不可用。

PyCharm 提供对 Python 运行/调试配置的调试支持。

配置基于 Docker 的解释器并在 Docker 容器中 调试您的 Python 脚本。

调试 Gevent 代码时，Python 调试器挂起。

Gevent 兼容模式未启用。

在 设置 对话框（Ctrl+Alt+S ）中，导航到 构建、执行、部署 | Python 调试器 并选中 Gevent 兼容 复选框。

在您的 PyQt 代码中报告了一些导入错误。

PyQt 已安装在解释器中，但未在应用程序代码中导入。

在 设置 对话框（Ctrl+Alt+S ）中，导航到 构建、执行、部署 | Python 调试器 ，并清除 PyQt 兼容 复选框。 此模式默认启用。

调试过程很慢。

调试器不仅在进程因异常终止时停止，还会在每次抛出异常时停止（即使异常被捕获且未导致进程终止）。

在 断点 对话框（运行 | 查看断点 ）中清除 引发时 复选框。

在您首次尝试附加到本地进程时出现以下错误消息： ptrace: Operation not permitted。

这是 Ubuntu 的 已知问题。

确保 kernel.yama.ptrace_scope 内核参数设置为 0。 您可以使用命令 sudo sysctl kernel.yama.ptrace_scope=0 临时更改其值，或通过将 kernel.yama.ptrace_scope = 0 行添加到 /etc/sysctl.d/10-ptrace.conf 文件中永久设置其值。

Cython 加速

显示以下错误消息：

Python.h: no such file or directory。

您缺少 Python 的头文件和静态库。

使用您的包管理器在系统范围内安装 python-dev 包。

在 Linux 上，您可以运行以下命令：

sudo apt-get install python-dev

要为特定的 Python 版本安装包，请使用 python-dev<version>。 例如：

sudo apt-get install python3.11-dev

显示以下错误消息：

Command 'gcc' failed with exit status 1。

您缺少 C 编译器。

安装 C 编译器以便为调试器构建 Cython 扩展。 有关更多信息，请参阅 Cython 文档。

您已在 Cython 加速扩展通知中点击了 安装 链接，但 PyCharm 仍反复提示安装它。

您没有对 PyCharm 使用的 目录的写入权限。

检查并修改您的权限。

打包

包安装失败。

pip 对于特定的 Python 解释器不可用，或者未满足任何安装要求。

  • 如果 pip 不可用，请为所需的 Python 解释器安装它（请参阅相应的 故障排除提示）。

  • 查阅特定包的产品文档，以确保它可以在您的操作系统和目标 Python 解释器中安装。 此外，请检查是否需要满足任何其他系统要求。

Docker （请参阅 Docker 排错）

文件监视器 您可能会在 首选项/设置 | 工具 | 文件监视器 窗口中注意到以下消息。

Unknown Scope error

文件监视器使用在此项目中未定义的作用域。

双击观察器并选择可用的作用域或创建一个新的。

Invalid executable

该项目使用了一个已被删除的全局 File Watcher。

使用 移除 按钮 移除 从列表中删除观察者，或编辑它以创建一个具有相同名称的新全局观察者。

部署

使用 SSH 配置时的错误消息：

Connection to <server> failed: SSH: invalid privatekey: [<key>. SSH: invalid privatekey: <key>

PyCharm 不支持 OpenSSH 密钥的 RFC 4716 格式。

  • 使用 ssh-add 命令将私钥添加到 ssh-agent （有关更多详细信息，请参阅 ssh.com）。

  • 在 添加 Python 解释器 对话框中重复配置步骤。

  • 使用 ssh-add 命令将私钥添加到 ssh-agent （有关更多详细信息，请参阅 ssh.com）。

  • 在 设置 对话框（Ctrl+Alt+S ）中，选择 构建、执行、部署 | 部署 ，然后选择您的 SFTP 部署配置。

    在 身份验证 列表中选择 OpenSSH 配置和身份验证代理。

运行 菜单中没有可用的 配置文件 命令。

  • 此功能仅在 PyCharm Pro 中可用。

  • 与 PyCharm Pro 捆绑的 Diagrams 插件已被禁用。

检查 PyCharm 的版本，并在 插件设置 中启用 图表 插件。

在某些情况下，您可能需要执行诊断步骤，以确定问题是出现在 PyCharm 中还是在您的工作环境中。 以下是一些有用的提示和技巧。

故障排除案例

诊断操作

在 PyCharm 和终端窗口中运行应用程序时，您遇到了不同的行为。

使用 PyCharm 项目设置中指定的 Python 版本运行您的脚本：

  1. 在 PyCharm 中，打开 设置 对话框 Ctrl+Alt+S ，导航到 项目 < project name> | Python 解释器。

  2. 点击 解释器 ，靠近 Python 解释器 字段并选择 显示全部...。 您在项目中使用的解释器将被选中为可用解释器列表中的一项。

  3. 点击 编辑解释器 并从 解释器路径 字段中复制路径。

  4. 现在，使用复制的路径在终端窗口中运行您的脚本

    <copied python interpreter path> <path to the python script>\my_script.py。 例如， C:\Python27\python.exe C:\Samples\my_script.py

  1. 在 PyCharm 中，打开 首选项 对话框 Ctrl+Alt+S ，导航到 项目 < project name> | Python 解释器。

  2. 点击 解释器 ，靠近 Python 解释器 字段并选择 显示全部...。 您在项目中使用的解释器将被选中为可用解释器列表中的一项。

  3. 点击 编辑解释器 并从 解释器路径 字段中复制路径。

  4. 现在，使用复制的路径在终端窗口中运行您的脚本

    <copied python interpreter path> <path to the python script>/my_script.py。 例如， /Users/jetbrains/bin/python3 /Users/jetbrains/Samples/my_script.py

如果您的应用程序行为仍然不同，请联系支持服务 pycharm-support@jetbrains.com。

特定 Python 解释器未安装所需的包。 为特定 Python 解释器安装的包版本已过时。

运行以下命令以安装所需的包：

<path to the python executable>\python.exe -mpip install '<package>'

例如， C:\Python27\python.exe -mpip install 'Flask'

执行这些命令后，将安装指定包的最新版本。

要安装特定版本的包，请使用以下表达式：

  • '<package>==<package_version>' – 安装包的特定版本

  • '<package>>=<package_version>' – 安装大于指定版本或更高版本的包

  • '<package>~=<package_version>' – 安装与指定版本兼容的包

例如，以下命令安装与版本 1.0.2 兼容的 Flask： C:\Python27\python.exe -mpip install 'Flask~=1.0.2'

<path to the python executable/python -mpip install '<package>'

例如， /Users/jetbrains/anaconda3/bin/python -mpip install 'Flask'

执行这些命令后，将安装指定包的最新版本。

要安装特定版本的包，请使用以下表达式：

  • '<package>==<package_version>' – 安装包的特定版本

  • '<package>>=<package_version>' – 安装大于指定版本或更高版本的包

  • '<package>~=<package_version>' – 安装与指定版本兼容的包

例如，以下命令安装与版本 1.0.2 兼容的 Flask： /Users/jetbrains/anaconda3/bin/python -mpip install 'Flask~=1.0.2'

尝试安装包时，您发现 pip 对于特定的 Python 解释器不可用。

尝试从标准库引导安装 pip：

<path to the python executable>\python.exe -m ensurepip --default-pip

例如， C:\Python27\python.exe -m ensurepip --default-pip

<path to the python executable/python -m ensurepip --default-pip

例如， /Users/jetbrains/anaconda3/bin/python -m ensurepip --default-pip

有关 pip 安装的更多信息，请参阅 packaging.python.org

最后修改日期： 2025年 9月 26日
键位图参考文件类型问题