Python开发模式下运行脚本出现ModuleNotFoundError问题求助

这问题我之前帮好几个开发者踩过坑，核心差异在于直接运行脚本和开发模式安装后运行时，Python的模块搜索路径（sys.path）逻辑完全不同。咱们一步步拆解解决：

先确认你的项目结构是否合规 #

首先得确保你的目录结构是标准的Python包结构，do/目录下必须有__init__.py（空文件就行，用来标记这是一个Python包），大概长这样：

your-project-root/
├── setup.py
└── do/
    ├── __init__.py
    ├── do.py       # 你的主脚本
    └── custom_mod.py  # 你要导入的自定义模块

如果没有__init__.py，开发模式安装后Python不会把do/当作一个可导入的包，这是常见的低级错误。

1. 修正导入语句的写法 #

直接运行python do.py时，Python会把当前脚本所在的do/目录加入sys.path，所以你写import custom_mod能直接找到同目录的模块。但开发模式安装后，Python是从site-packages里的链接指向你的项目根目录，这时候do/是一个顶层包，同目录的模块属于do包的子模块，不能直接用裸导入。

你有两种修正方式：

• 相对导入（推荐，适合包内部模块引用）：
  在do.py里改成：

  from . import custom_mod
  

  注意：相对导入只能在包内部使用，直接运行python do.py时会报错，但开发模式安装后用正确方式运行就没问题。
• 绝对导入（明确指定包名）：
  改成：

  from do import custom_mod
  

  这种写法在两种运行方式下都能生效，但需要确保do包在sys.path里。

2. 检查setup.py的配置是否正确 #

开发模式安装（pip install -e .）的核心是让Python识别你的包，所以setup.py必须正确声明要安装的包。这里给你一个标准的配置示例：

from setuptools import setup, find_packages

setup(
    name="your-project-name",  # 随便起个项目名
    version="0.1.0",
    packages=find_packages(),  # 自动扫描所有带__init__.py的包（这里就是do/）
    # 推荐配置控制台入口，避免手动运行脚本的路径问题
    entry_points={
        "console_scripts": [
            "run-do=do.do:main",  # 假设do.py里有个main函数作为入口
        ]
    }
)

如果你的setup.py里用的是packages=['do']也可以，但find_packages()更灵活，后续加子包不用改配置。

3. 用正确的方式运行开发模式下的脚本 #

修正完导入和setup.py后，按以下步骤操作：

1. 回到项目根目录（就是有setup.py的那个目录）
2. 重新安装开发模式：pip install -e .
3. 运行脚本的两种正确方式：
   • 如果你配置了entry_points，直接在终端输入run-do（就是setup.py里console_scripts指定的命令），这会自动调用do.do里的main函数，导入完全正常。
   • 或者用模块方式运行：python -m do.do，-m参数会让Python把do包加入sys.path，正确解析相对/绝对导入。

为什么之前直接运行没问题？ #

再补个小知识点帮你理解：直接运行python do.py时，脚本会被当作__main__模块，Python会把脚本所在目录（do/）加到sys.path的最前面，所以同目录的模块能直接找到。但开发模式安装后，Python是从项目根目录识别do包，这时候do/不在sys.path顶层，裸导入自然找不到模块。

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