GitHub仓库本地Python包导入配置的最佳实践咨询

针对你的仓库结构和需求，这里有几个符合Python生态标准、兼顾共享与可复现性的最优方案，比临时添加sys.path要优雅得多：

方案1：将项目声明为可安装包（推荐用于团队协作/长期维护） #

这是Python社区最推崇的做法，通过pyproject.toml（现代标准）将你的项目标记为可安装包，其他人克隆仓库后只需一步操作就能正常导入模块。

步骤： #

1. 在仓库根目录创建pyproject.toml文件，内容如下：

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

[project]
name = "repo-name"
version = "0.1.0"
# 声明要包含的包目录
packages = ["repo_name", "packages"]
# 指定包的根目录为src
package_dir = {"": "src"}

注意：如果你的src/repo-name目录名包含横杠，Python导入时需要用下划线（比如import repo_name.packages.mypackage1），或者你可以把目录名改成repo_name来匹配导入语法。

2. 以开发模式安装项目：
   在仓库根目录运行以下命令：

pip install -e .

这个命令会把你的项目链接到Python的site-packages目录，既不会复制文件，又能让Python识别你的包结构。

优势： #

• 任何人克隆仓库后，只需执行pip install -e .就能正常导入模块，无需手动配置路径
• 支持在任意目录运行do_something.py，直接用import packages.mypackage1或import repo_name.packages.mypackage1即可
• 完全符合Python包规范，方便后续发布到PyPI（如果需要）

方案2：使用python -m参数运行脚本（适合快速测试/临时使用） #

如果你不想安装包，也可以通过Python的-m模块运行方式，让Python自动识别仓库的根目录路径。

步骤： #

在仓库根目录执行以下命令：

python -m scripts.do_something

此时Python会将仓库根目录添加到sys.path中，你可以在do_something.py里直接使用以下导入语句：

from src.packages import mypackage1
# 或者
from src.repo_name.packages import mypackage1

优势： #

• 无需修改任何配置文件，零成本快速生效
• 避免了手动添加sys.path的“取巧”写法
• 保持仓库结构的纯净性

为什么你之前的方法会报错？ #

简单解释下问题根源：

1. import repo-name.packages.mypackage1报错：因为Python默认不会把仓库根目录加入sys.path，所以找不到repo-name包
2. 相对导入报错：当你直接运行do_something.py时，它被当作顶层脚本（__main__模块），没有父包上下文，所以相对导入..会找不到父级路径

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