如何排查Python中的‘ModuleNotFound’错误？含自定义模块排查方法

一、基础排查（先确认这几点） #

• 检查模块/包存在性：第三方包用pip list或pip show <包名>确认安装；自定义模块直接看对应.py文件或目录是否存在
• 验证虚拟环境状态：用which python（Linux/macOS）或where python（Windows）确认当前使用的Python解释器路径，确保和安装包时的解释器一致
• 核对拼写与大小写：Python模块名区分大小写，导入语句的名称必须和实际文件/目录名完全匹配

二、进阶排查步骤（按顺序来） #

1. 查看Python的模块搜索路径 #

直接在Python交互环境里运行以下代码，就能得到Python查找模块的优先级路径列表（从左到右依次查找）：

import sys
print(sys.path)

自定义模块的所在目录必须出现在这个列表里，Python才能找到它。

2. 确认模块目录在搜索路径内 #

• 单个.py文件：检查它的父目录是否在sys.path中
• 包（带__init__.py的目录）：检查包的父目录是否在sys.path中（比如你有my_package/__init__.py，那么my_package所在的文件夹要在搜索路径里）

3. 理清__init__.py的作用差异 #

• 带__init__.py的目录会被识别为传统包：可以在这个文件里定义包级变量、预导入子模块，或者控制from <包> import *的导入范围
• 不带__init__.py的目录（Python 3.3+）是命名空间包：无需初始化文件，适合跨目录共享同一个包名的场景，但没法通过__init__.py做包初始化操作
• 如果导入子模块出错（比如from my_package.sub import func），要确认my_package是合法包、sub.py存在，且my_package的父目录在搜索路径里

4. 排查导入方式的问题 #

• 区分相对导入和绝对导入：包内部用相对导入（比如from .sub import func），外部调用要用绝对导入（from my_package import sub），混用极易出错
• 避免和标准库/第三方包重名：如果你的自定义模块和标准库模块（比如math.py）同名，Python会优先加载搜索路径里靠前的那个，导致你的模块被“覆盖”

5. 验证解释器一致性 #

有时候你用pip install安装的包属于系统Python，但运行代码用的是虚拟环境的Python（反之亦然）。用python -m pip list确认当前解释器对应的包列表，避免环境不匹配。

三、避免问题的工具与最佳实践 #

• 临时调试路径（仅用于测试）：在代码开头临时添加模块目录到搜索路径：

  import sys
  sys.path.append("/path/to/your/module/dir")
  

  注意这是临时方案，不要用于生产代码
• 设置PYTHONPATH环境变量：把模块所在目录加入PYTHONPATH，Python启动时会自动将其加入sys.path
  • Linux/macOS：终端执行export PYTHONPATH="/path/to/your/dir:$PYTHONPATH"，或写入~/.bashrc/~/.zshrc永久生效
  • Windows：在系统环境变量中添加PYTHONPATH，值为模块所在目录
• 可编辑安装自定义包：如果是自己开发的包，在包含setup.py或pyproject.toml的目录执行pip install -e .，包会以可编辑模式安装，修改代码后无需重新安装就能被Python识别
• 规范项目结构：把自定义模块统一放在项目根目录的src文件夹下，配合pyproject.toml（用setuptools或poetry管理），确保包能被正确识别
• 不要在工作目录乱放模块：当前工作目录默认在sys.path里，但如果和其他路径的模块重名，会引发冲突

内容的提问来源于stack exchange，提问作者MythicalMoose