PyCharm 故障排除在使用 PyCharm 时，您可能会遇到一些警告或错误消息。 本章提供了已知问题的解决方案和解决方法列表。
您还可以找到有关故障排除和执行工作环境基本诊断的建议。
项目设置
代码编辑
代码补全
调试
Cython 加速
打包
Docker
文件监视器
部署
性能分析器
故障排除提示
性能问题
已报告的问题
可能的原因
解决方案
项目设置
在 首选项/设置 | 项目 | 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 和 macOS 上，您可以运行以下命令：
sudo apt-get install python-dev
要为特定的 Python 版本安装包，请使用 python-dev
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
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 版本运行您的脚本：
在 PyCharm 中，打开 设置 对话框 Ctrl+Alt+S ，导航到 项目 < project name> | Python 解释器。
点击 ，靠近 Python 解释器 字段并选择 全部显示…。 您在项目中使用的解释器将被选中为可用解释器列表中的一项。
点击 并从 解释器路径 字段中复制路径。
现在，使用复制的路径在终端窗口中运行您的脚本
在 PyCharm 中，打开 首选项 对话框 Ctrl+Alt+S ，导航到 项目 < project name> | Python 解释器。
点击 ，靠近 Python 解释器 字段并选择 全部显示…。 您在项目中使用的解释器将被选中为可用解释器列表中的一项。
点击 并从 解释器路径 字段中复制路径。
现在，使用复制的路径在终端窗口中运行您的脚本
如果您的应用程序行为仍然不同，请联系支持服务 pycharm-support@jetbrains.com。
特定 Python 解释器未安装所需的包。 为特定 Python 解释器安装的包版本已过时。
运行以下命令以安装所需的包：
例如， C:\Python27\python.exe -mpip install 'Flask'
执行这些命令后，将安装指定包的最新版本。
要安装特定版本的包，请使用以下表达式：
'
'
'
例如，以下命令安装与版本 1.0.2 兼容的 Flask： C:\Python27\python.exe -mpip install 'Flask~=1.0.2'
例如， /Users/jetbrains/anaconda3/bin/python -mpip install 'Flask'
执行这些命令后，将安装指定包的最新版本。
要安装特定版本的包，请使用以下表达式：
'
'
'
例如，以下命令安装与版本 1.0.2 兼容的 Flask： /Users/jetbrains/anaconda3/bin/python -mpip install 'Flask~=1.0.2'
尝试安装包时，您发现 pip 对于特定的 Python 解释器不可用。
尝试从标准库引导安装 pip：
例如， C:\Python27\python.exe -m ensurepip --default-pip
例如， /Users/jetbrains/anaconda3/bin/python -m ensurepip --default-pip 有关 pip 安装的更多信息，请参阅 packaging.python.org 最后修改日期： 2025年 4月 23日键位图参考文件类型问题