使用setup.py构建命令行工具时遭遇ModuleNotFoundError: No module named 'src'问题

这个问题我之前开发Python命令行工具时也碰到过，核心原因就是Python在两种运行场景下的模块查找逻辑不一样，咱们一步步拆解解决：

为什么会出现这个错误？ #

• 当你在s3_md5目录下直接运行python cmd.py时，Python会把当前目录（也就是s3_md5）加入到模块查找路径（sys.path）里，所以import src.xxx能直接找到同级的src目录。
• 但当你通过setup.py安装后，你的s3_md5包会被放到Python的site-packages目录下，此时sys.path指向的是site-packages，src是s3_md5的子包，必须通过s3_md5.src.xxx的绝对路径才能访问，直接import src自然会找不到。

而你提到的两种导入方式各自有问题：

• 用s3_md5.src.cli：安装后能正常运行，但本地直接跑cmd.py时，Python会去site-packages里找已安装的s3_md5包，而不是你本地开发的代码，导致调试不便。
• 用相对导入：安装后能运行，但本地直接跑cmd.py时，因为脚本不属于包的一部分，Python会报错“no known parent”。

推荐的解决方案 #

我个人最常用的是统一使用绝对导入+本地用模块方式运行，既能保证安装后的兼容性，又能方便本地开发调试：

步骤1：修改cmd.py的导入方式为绝对路径

把所有导入改成以s3_md5开头的绝对导入：

'''driver'''
from time import perf_counter

from boto3 import client
from s3_md5.src.cli import parse_args
from s3_md5.src.logger import logger
from s3_md5.src.s3_md5 import parse_file_md5


def run():
    # 你的业务逻辑代码
    pass


if __name__ == "__main__":
    run()

步骤2：本地开发时用-m参数运行脚本

不要直接在s3_md5目录下跑python cmd.py，而是回到项目根目录（也就是有setup.py的那个目录），执行：

python -m s3_md5.cmd

用-m参数运行时，Python会把项目根目录加入到sys.path，并且把s3_md5当作一个包来处理，这时候绝对导入会优先使用你本地的代码，而不是已安装的包，完美解决调试问题。

备选方案：兼容两种场景的导入逻辑

如果你实在习惯直接跑cmd.py，可以在导入时加个异常捕获，兼容两种场景：

'''driver'''
from time import perf_counter

try:
    # 安装后的场景：用绝对导入
    from s3_md5.src.cli import parse_args
    from s3_md5.src.logger import logger
    from s3_md5.src.s3_md5 import parse_file_md5
except ImportError:
    # 本地直接运行的场景：直接导入src
    from src.cli import parse_args
    from src.logger import logger
    from src.s3_md5 import parse_file_md5


def run():
    # 你的业务逻辑代码
    pass


if __name__ == "__main__":
    run()

不过这种方式有点hack，长期来看还是推荐用-m的方式，更符合Python的包规范。

额外提醒 #

你也可以检查一下setup.py里的find_packages配置，你当前的packages=find_packages(exclude=["test", "venv"])是没问题的，它会自动把s3_md5下的所有子包（包括src）都打包进去，所以安装后src目录确实会存在，问题不在打包环节，而是导入路径的问题。

备注：内容来源于stack exchange，提问作者sakib11