sys.path含模块路径仍报ModuleNotFoundError故障排查

故障根因判定 #

目录下仅存在.dist-info元数据文件夹、缺失对应名称的实际代码包，就是本次导入失败的直接原因。
Python解释器导入第三方模块时，只会识别sys.path搜索路径下与导入名匹配的代码目录或单文件模块。.dist-info是pip用来记录包版本、依赖关系、安装信息的元数据目录，本身不包含可执行的项目代码，不会被解释器识别为可导入模块。正常安装的第三方包必然是「代码目录+同版本.dist-info目录」成对存在，缺失代码目录时触发ModuleNotFoundError是符合预期的表现。

仅生成.dist-info未部署代码的触发原因 #

这类异常基本来自三类场景，按出现概率从高到低排列：

• 安装源上的对应版本包本身打包错误。这是小众第三方库出现该问题的最常见原因：包维护者编写打包配置（setup.py/pyproject.toml）时漏配了代码目录的打包规则，上传到公共源的安装包本身就只包含元数据、没有核心代码，pip执行安装流程时解压完元数据就判定安装完成，不会校验代码文件是否存在。
• 安装过程被异常中断。安装流程中写入代码文件的步骤如果碰到磁盘空间不足、目录权限受限、安全软件拦截写入等问题，pip没有捕获抛出可见报错就提前终止，会留下先写入的.dist-info残留目录。
• 安装缓存/残留元数据误导pip判定。如果之前安装该包失败留下了.dist-info残留，后续执行安装/升级时pip会误判当前环境已经安装了最新版本，直接跳过代码部署步骤，提示安装成功。

修复方案 #

按顺序尝试以下操作即可解决：

1. 跳过本地缓存强制重装，执行命令：

   pip install --no-cache-dir --force-reinstall disagree
   

2. 如果强制重装后仍然缺失代码目录，说明你当前使用的安装源上的包本身打包损坏，可以直接下载对应版本的源码包，手动把源码包内的disagree代码文件夹解压到你之前查到的site-packages目录下，即可正常导入。

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