Python包导入报错求助：无需修改sys.path的解决方案

问题背景 #

项目结构如下：

├── my_app
    ├── __init__.py
    ├── my_pkg
    │   ├── __init__.py
    │   ├── utils.py
    │   ├── app.py
    ├── other_pkg...
    │   ├── __init__.py
    │   ├── ...
    ├── ...

需要在my_app/my_pkg/app.py中导入utils，且能在任意位置运行该文件（比如在my_app目录下执行python my_pkg/app.py），但使用from my_app.my_pkg import utils时抛出ModuleNotFoundError: No module named my_app，不想通过修改sys.path解决问题。

原因分析 #

直接运行app.py这类脚本文件时，Python会将**脚本所在的目录（即my_pkg）**添加到模块搜索路径sys.path中，而非my_app的父目录。此时my_app不在搜索路径里，Python无法识别它为顶级包，自然找不到my_app.my_pkg这个模块路径。

可行解决方案 #

方案1：相对导入 + 以模块方式运行 #

在app.py中使用相对导入替代绝对导入：

# my_app/my_pkg/app.py
from . import utils

# 你的业务代码
if __name__ == "__main__":
    utils.some_function()

然后通过Python的-m参数以模块方式运行：

• 在my_app的父目录下执行：

  python -m my_app.my_pkg.app
  

• 在my_app目录下执行：

  python -m my_pkg.app
  

-m参数会让Python将当前执行命令的目录加入sys.path，从而正确识别顶级包结构，相对导入也能正常工作。

方案2：使用__main__.py作为包入口 #

在my_pkg目录下创建__main__.py文件，将app.py的核心逻辑移到这里，或者在__main__.py中导入app模块：

# my_app/my_pkg/__main__.py
from .app import main  # 假设app.py中有main函数作为入口

if __name__ == "__main__":
    main()

之后可以直接以包为单位运行：

• 在my_app目录下执行：

  python -m my_pkg
  

• 在my_app的父目录下执行：

  python -m my_app.my_pkg
  

这种方式同样不需要修改sys.path，Python会自动识别包结构。

方案3：开发模式安装包 #

在my_app的父目录下创建pyproject.toml配置文件：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my_app"
version = "0.1.0"

然后执行开发模式安装命令：

pip install -e .

安装完成后，my_app会被识别为系统级可导入的包，此时：

• 你可以在app.py中正常使用绝对导入from my_app.my_pkg import utils
• 任意位置都可以通过python -m my_app.my_pkg.app运行脚本
• 开发模式下修改代码会实时生效，无需重新安装

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