使用setuptools构建发布PyPI包后出现模块导入失败问题

核心问题原因 #

安装包后，Python的模块搜索路径中不会包含src目录，代码里用from src.graph import Graph这种基于项目根目录的绝对导入，在包安装后会因找不到src模块而报错。

步骤1：调整项目结构 #

把所有模块文件移入src/mypackage目录，并添加空的__init__.py文件（用于标识这是Python包），最终结构如下：

.
├── LICENSE
├── README.md
├── pyproject.toml
├── setup.py
├── src
│   └── mypackage
│       ├── __init__.py
│       ├── graph.py
│       ├── resolver.py
│       ├── sql_node.py
│       └── topological_sort.py
└── tests
    ...

步骤2：修正内部导入语句 #

将代码中所有基于src的导入改为相对导入或基于包名的绝对导入：

• 相对导入（推荐包内部使用）：resolver.py中的from src.graph import Graph改为from .graph import Graph
• 绝对导入：改为from mypackage.graph import Graph

步骤3：配置打包文件 #

1. 更新pyproject.toml #

确保包含正确的包查找规则：

[build-system]
requires      = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["src"]
include = ["mypackage*"]

2. 简化setup.py（可选，保留更兼容） #

from setuptools import setup, find_packages

setup(
    name="mypackage",  # 替换为你的包名
    version="0.1.0",   # 替换为你的版本号
    packages=find_packages(where="src"),
    package_dir={"": "src"},
)

步骤4：测试安装与导入 #

1. 卸载旧版本包：

pip uninstall -y mypackage

2. 构建包：

python -m build

3. 安装本地包：

pip install dist/mypackage-0.1.0.tar.gz  # 替换为实际生成的包文件名

4. 验证导入：

python -c "from mypackage.resolver import YourClass"  # 替换为你要导入的类/函数

关键注意事项 #

• 不要在src目录下留零散模块文件，所有代码必须放在mypackage包目录内，否则安装后无法被正确识别。
• 相对导入仅适用于包内部模块，直接运行包内单个文件（如python src/mypackage/resolver.py）会报错，但作为包导入使用时正常。

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