pip安装自定义package成功却无法导入，报ModuleNotFoundError求助

问题场景还原 #

你的目录结构如下：

package/
    __init__.py
    setup.py

setup.py代码：

from setuptools import setup, find_packages
setup(
    name="package",
    version="0.0.1",
    packages=find_packages(),
)

执行安装命令后显示成功：

pip install ./package
# 终端输出：
Processing ./package
Installing collected packages: package
Running setup.py install for package ... done
Successfully installed package-0.0.1

但在Python中导入时触发错误：

import package
# 报错：ModuleNotFoundError

常见排查及解决方法 #

1. 优先检查pip与Python版本的匹配性 #

这是最常见的诱因——你用pip安装的包可能不在当前运行的Python环境的依赖目录里。比如系统同时装了Python2和Python3，pip默认绑定Python2，而你运行的是Python3（用python3命令启动），反之亦然。

验证步骤：

• 查看pip对应的Python版本：

  pip --version
  

• 查看当前运行的Python版本：

  python --version
  

如果版本不匹配，就用对应版本的pip重新安装：
比如给Python3安装就用：

pip3 install ./package

之后用python3启动解释器再尝试导入。

2. 确认包的安装路径是否在Python的搜索路径中 #

先通过pip查看包的安装位置：

pip show package

输出里的Location字段会显示包的安装目录（比如/usr/local/lib/python3.9/site-packages）。

接着在Python中查看当前环境的搜索路径：

import sys
print(sys.path)

如果Location对应的路径不在sys.path列表里，说明你运行的Python环境和安装包的环境不一致，需要切换到正确的环境。

3. 检查__init__.py文件状态 #

空的__init__.py本身是可以让包被识别的，但如果文件存在语法错误、权限不足（当前用户无读取权限），也会导致导入失败。可以打开文件确认内容正常，同时检查文件权限是否合理。

4. 虚拟环境的一致性问题 #

如果你使用了虚拟环境，可能存在安装包时和运行Python时激活的环境不一致的情况。解决方法：

# 激活目标虚拟环境（以venv为例）
source venv/bin/activate
# 重新安装包
pip install ./package
# 启动Python并尝试导入
python
import package

总结 #

绝大多数情况下，问题出在pip与Python版本不匹配导致包安装到了错误的环境中，优先排查版本对应关系即可解决问题。

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