科技 · 实用指南
pip 显示已安装却报 ModuleNotFoundError？先证明解释器与导入路径
从失败进程确认 Python，核对该解释器可见的分发元数据、真实导入名与 sys.path，最后用干净导入证明修复。
pip 安装成功与 import 失败可以同时成立，因为它们可能指向不同解释器、不同名称或不同搜索路径。
从失败进程内部开始，把后续命令都绑定到它报告的绝对 Python 路径，再证明元数据、名称映射、路径解析与模块来源。
先保留失败运行时
重跑准确失败命令，保存工作目录与完整 traceback；由同一启动方式输出 sys.executable、sys.version、sys.prefix、sys.base_prefix 和 sys.path。终端、IDE、notebook、service 与 shebang 都可能选中不同解释器。
不要先用 sudo pip、--user、全局 PYTHONPATH 或复制 site-packages 路径。第一份有效证据是失败进程自己报告的绝对解释器。
让该解释器检查分发
明确使用该路径运行 /absolute/python -m pip show <distribution>，记录 Name、Version、Location，必要时加 --files。另一个 pip 的成功结果不能证明本解释器可见。
若本解释器查不到分发，按项目锁定文件安装到目标环境；若 Location 不在 sys.path 中，检查激活、user-site、pyvenv.cfg、service 或 container 边界。
分开分发名与导入名
pip 接受的是 distribution 名，import 使用的是 import package 名。Python Packaging 指南说明二者不必一一对应，例如 Pillow 使用 PIL。
核对项目文档中的导入名、安装文件，并可在失败解释器中查询 importlib.metadata.packages_distributions()。不要因 import <distribution-name> 失败就断言安装失败。
解释搜索路径而不是打补丁
Python 会依据脚本或当前目录、环境变量、可执行文件线索、虚拟环境配置和 site 处理构造 sys.path。用 python -m site 记录 USER_SITE 与 ENABLE_USER_SITE。
service 可能禁用 user site，IDE 或 notebook 可能保留旧 kernel，shebang 也可能指向另一解释器。修复最小启动或环境边界，避免全局 PYTHONPATH 和随意 sys.path.append。
排除遮蔽并要求退出证明
检查项目目录是否存在与目标模块同名的文件或目录。导入前用 importlib.util.find_spec，成功后记录 module.__file__，确认没有本地文件抢先遮蔽。
只有原失败解释器显示预期 Location、从预期路径解析正确导入名、在干净进程导入成功且原脚本通过，事件才关闭。保存 executable、Location、path/site、find_spec 与模块文件证据。
