运行Pip发布的Python包时遭遇ModuleNotFoundError问题求助

问题原因 #

本地直接执行python start.py时，当前工作目录会被加入Python的模块搜索路径（sys.path），所以能直接找到同目录的utils.py；但安装为Pip包后，src作为一个包被放置在site-packages目录下，此时Python的搜索路径不包含src内部目录，直接import utils会找不到模块。

解决方案 #

1. 修改模块导入语句 #

将start.py中的import utils改为相对导入：

from . import utils

这种写法明确告诉Python从当前包（即src目录）下导入utils模块。

2. 修正setup.py配置 #

确保setup.py正确识别你的包结构，以下是标准配置示例：

from setuptools import setup, find_packages

setup(
    name="microservicebus-py",
    version="0.1.0",
    # 自动发现所有包含__init__.py的包
    packages=find_packages(),
    entry_points={
        'console_scripts': [
            # 映射命令到模块的main函数
            'microservicebus-py = src.start:main'
        ]
    }
)

3. 确保包结构规范 #

在src目录下添加空的__init__.py文件，让Python将src识别为一个合法的Python包：

your-project/
├── src/
│   ├── __init__.py
│   ├── start.py
│   └── utils.py
└── setup.py

验证步骤 #

1. 重新打包：python setup.py sdist bdist_wheel
2. 安装测试包：pip install dist/microservicebus-py-0.1.0.tar.gz
3. 执行命令：microservicebus-py，确认不再出现模块找不到的错误

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