打包至PyPI的Python库中如何动态导入用户项目生成模块

问题根因 #

Python 加载模块时严格按照sys.path列表的路径顺序搜索，你遇到的本地正常、打包安装后报错的差异，完全来自两种运行场景下的sys.path组成区别：

• 本地未打包调试时，你在项目根目录直接运行入口函数，Python 会自动把当前工作目录加入sys.path首位，因此可以顺利搜索到当前目录下由mlab命令生成的laboratory包结构。
• 通过pip安装发布的包后，console_scripts会在Python环境的Scripts目录下生成独立的可执行启动文件。运行这个脚本时，Python 默认会把可执行文件所在的Scripts目录加到sys.path最前面，此时存放laboratory目录的用户项目根路径，根本没有被纳入模块搜索范围，自然会抛出ModuleNotFoundError。
• 你之前写的代码还存在顺序逻辑错误：先执行模块导入、再切换工作目录，哪怕后续切了路径，导入动作已经完成，依然会找不到模块；而且原代码在判断目录不存在后没有中断执行，会继续往下走导入流程，进一步放大报错。

可直接复用的修正实现 #

不需要切工作目录，核心逻辑是在导入用户侧模块前，显式把当前工作目录加入sys.path搜索列表，再执行导入和调用：

import os
import sys

def rlab():
    """
    This shell command is used to run a lab.
    """
    current_root = os.getcwd()
    lab_target_dir = os.path.join(current_root, "laboratory")
    if not os.path.isdir(lab_target_dir):
        print("No lab exists... run the mlab command to make a lab.")
        return

    # 关键：将项目根路径加入模块搜索范围
    if current_root not in sys.path:
        sys.path.insert(0, current_root)

    # 路径配置完成后再执行导入
    try:
        from laboratory.labmain import main
    except ImportError:
        print("Failed to load lab module, please check the integrity of laboratory directory.")
        return

    # 直接调用main方法，无需额外切换工作目录
    main()

避坑注意事项 #

• 绝对不要保留原代码里的os.chdir("laboratory")逻辑：强制切换工作目录会导致用户项目中所有基于相对路径的文件读取、资源引用全部失效，完全没有必要。
• 检查你的打包配置：确认setup.py/pyproject.toml中没有把laboratory这个目录打包进发布的库本身，否则安装后site-packages下会存在同名的空laboratory包，导入时会优先匹配这个内置包，永远读不到用户项目下生成的实际内容。
• 尽量避免命名冲突：如果你的主库本身已经使用laboratory作为内置包名，建议把mlab命令生成的目录名改成其他辨识度高的名称（比如user_lab），从根源上避免导入时的路径匹配冲突。

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