PyCharm 2025.3 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 使用的目录 的写入权限。

检查并修改您的权限。

打包

软件包安装失败。

对于某个 Python 解释器， pip 不可用，或者未满足某项安装要求。

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

  • 请查阅特定软件包的产品文档，确保其可在您的操作系统上安装，并适用于目标 Python 解释器。 另请检查是否需要满足其他系统要求。

Docker （参阅 Docker 疑难解答）

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

Unknown Scope error

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

双击该监视器，并选择一个可用的作用域，或创建一个新的作用域。

Invalid executable

该项目使用了已移除的全局文件监视器。

使用 移除 按钮 删除 从列表中删除该监视器，或编辑它以创建一个同名的新全局文件监视器。

部署

使用 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 中运行您的应用与在 Terminal 窗口中运行时的行为不一致。

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

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

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

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

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

    <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. 现在，在 Terminal 窗口中使用复制的路径运行您的脚本

    <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'

尝试安装软件包时，您发现对于某个 Python 解释器，pip 不可用。

尝试从标准库引导安装 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年 12月 2日
键位映射参考文件类型问题