1、先确认正在使用哪个 Python#

不要只看编辑器左下角显示的解释器，最好直接在终端里打印：

1
python -c "import sys; print(sys.executable)"

如果使用的是 conda 环境，也可以看：

1
conda info --envs

当前环境前面会有一个 *。很多导入失败的问题，本质上就是在 A 环境安装了包，却用 B 环境运行代码。

2、确认包是否安装在当前环境#

以 pandas 为例，可以这样检查：

1
python -m pip show pandas

如果没有输出，说明当前 Python 环境里没有安装这个包。安装时也尽量使用：

1
python -m pip install pandas

这样可以保证 pip 和 python 指向同一个环境，减少装错位置的问题。

3、检查文件名有没有冲突#

有时候我们会把自己的文件命名为：

1
pandas.py
2
torch.py
3
cv2.py

这样 Python 导入时会优先找到当前目录下的同名文件，导致真正的第三方库无法被导入。可以先检查当前目录：

1
dir

如果发现文件名和库名一样，建议改成更具体的名字，例如：

1
pandas_practice.py
2
torch_train_demo.py
3
image_read_test.py

改名后还要删除可能生成的缓存目录：

1
rmdir /s /q __pycache__

Linux 或 macOS 下可以用：

1
rm -rf __pycache__

4、确认项目内部模块路径#

如果导入的是自己写的模块，例如：

1
from utils.file_helper import read_data

需要确认运行命令是在项目根目录执行的。可以打印当前工作目录：

1
from pathlib import Path
2

3
print(Path.cwd())

如果工作目录不对，可以切换到项目根目录后再运行：

1
cd 项目目录
2
python main.py

也可以把项目整理成更清晰的结构：

1
project/
2
  main.py
3
  utils/
4
    __init__.py
5
    file_helper.py

其中 __init__.py 可以让目录更明确地被当作 Python 包来使用。

5、记录一条最小验证命令#

排查结束后，我习惯保留一条最小验证命令：

1
python -c "import pandas as pd; print(pd.__version__)"

如果这条命令可以运行，再去跑完整项目。这样可以把“环境问题”和“业务代码问题”分开判断。

总结#

ModuleNotFoundError 不要只盯着安装命令看。我的排查顺序是：先确认 Python 路径，再确认包是否装在当前环境，然后检查文件名冲突，最后看项目内部模块路径。按这个顺序查，基本能定位大多数导入失败问题。