Python本地项目库的文件布局与跨模块导入方法问询

1. src内部模块间的导入 #

比如database.py要导入utils.py中的my_helper，有两种规范写法：

• 相对导入：使用from .utils import my_helper，适合模块内部的相互引用，无需关注包的顶层名称，重构时更灵活。
• 绝对导入：使用from src.utils import my_helper，适合将src作为独立包的场景，当项目被添加到Python路径或安装后，这种写法更明确，能避免与第三方包重名冲突。

不推荐直接写from utils import my_helper，因为Python会优先从全局包路径查找utils，极易引发命名冲突。

2. 跨文件夹模块的导入（如webapp/app.py依赖src/database.py） #

主流方案有两种：

• 方案一：将项目根目录加入Python路径
  在app.py开头添加代码：

  import sys
  from pathlib import Path
  
  # 定位项目根目录（project/）并加入路径
  project_root = Path(__file__).parent.parent
  sys.path.append(str(project_root))
  
  # 之后即可正常导入
  from src.database import ...
  

• 方案二：将src作为可编辑包安装
  在project/目录下执行命令：

  pip install -e .
  

  这会将src注册为全局可导入的包，之后app.py里直接用绝对导入即可：

  from src.database import ...
  

  这种方式更规范，适合长期维护的项目，避免手动修改sys.path的繁琐。

3. notebooks目录下的导入 #

并非只能用sys.path方法，更推荐以下两种方式：

• 方法一：利用可编辑安装
  同样执行pip install -e .，之后在notebook中直接使用from src.utils import ...，无需修改路径。
• 方法二：在notebook开头添加路径
  如果不想安装包，可在notebook的第一个单元格写入：

  import sys
  from pathlib import Path
  
  # 定位项目根目录（根据notebook实际位置调整）
  project_root = Path.cwd().parent
  sys.path.append(str(project_root))
  
  from src.utils import ...
  

4. Python社区的统一共识 #

• 优先使用绝对导入，代码可读性更强，避免相对导入的层级混淆；内部模块间的小范围引用可酌情使用相对导入。
• 尽量避免硬编码sys.path，推荐用可编辑安装（pip install -e .）管理本地包，这是现代Python项目的标准做法。
• 项目结构遵循「src布局」（核心代码放在src目录），这是社区广泛认可的规范，能清晰分离核心代码与附属脚本、notebooks等内容。

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