Python包内如何正确导入模块？适配pytest及官方打包结构

一、先确认标准项目结构（以你的countach包为例） #

确保项目结构严格遵循官方推荐格式，这是解决所有导入问题的基础：

countach-project/
├── countach/
│   ├── __init__.py
│   ├── file1.py
│   ├── file2.py
│   └── tests/
│       ├── __init__.py
│       └── test_file1.py
├── pyproject.toml
└── setup.cfg（或setup.py）

二、同包内导入的正确姿势 #

1. 绝对导入的配置方法 #

如果偏好from countach import file2这类绝对导入，解决pytest找不到包的问题只需两步：

• 把项目根目录（countach-project/）加入Python环境变量：

  export PYTHONPATH=/path/to/countach-project:$PYTHONPATH
  

  之后执行python3 -m pytest即可正常识别包。
• 或者直接用pytest的根目录参数指定路径：

  python3 -m pytest --rootdir=/path/to/countach-project
  

2. 相对导入的合理使用 #

官方文档提到的相对导入“弊端”主要针对跨包场景，同包内使用完全合规且简洁，比如在file1.py中导入file2.py的函数：

from .file2 import functionName

这种写法无需依赖外部路径配置，稳定性更强。

3. __init__.py的规范写法 #

要实现countach.function的调用方式，不要直接写from file1 import function（易引发路径错误），改用相对或完整绝对导入：

# countach/__init__.py
from .file1 import function  # 推荐：相对导入，适配所有运行场景
# 或绝对导入：from countach.file1 import function

三、解决包冲突与模块找不到问题 #

1. 彻底清理旧版本包：

   pip uninstall -y countach
   pip show countach  # 确认无残留，输出“WARNING: Package(s) not found: countach”即清理完成
   

2. 用开发模式安装包，避免本地源码与已安装包冲突：
   在项目根目录执行：

   pip install -e .
   

   此方式会让Python优先使用本地源码，修改代码后无需重新安装。
3. 禁止在包目录内直接运行单个模块：
   不要在countach/目录下执行python file1.py，正确方式是在项目根目录运行：

   python -m countach.file1
   

四、总结 #

• 同包内优先用相对导入，简洁稳定且符合官方规范；
• 若用绝对导入，确保项目根目录在PYTHONPATH中，或通过pip install -e .进入开发模式；
• __init__.py用相对导入暴露对外接口，避免路径依赖；
• 开发阶段用pip install -e .替代临时安装wheel，从根源解决路径与冲突问题。

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