Setuptools/pyproject.toml控制台脚本无法导入主包：ModuleNotFoundError

你的核心问题是wheel包安装后，系统无法找到python3_template模块，这说明打包过程中包的结构或配置存在疏漏，导致模块未被正确安装到Python的site-packages目录中。以下是针对性的排查步骤和修复方案：

一、先确认项目目录结构（必须符合规范） #

确保你的目录结构是标准的Python包结构，示例如下：

python3-template-project/
├── pyproject.toml
├── python3-template.py       # 主目录运行的入口脚本
└── python3_template/         # 实际的Python包目录
    ├── __init__.py           # 必须存在，哪怕是空文件
    └── main.py               # 存放run()函数的文件（或直接写在__init__.py中）

如果python3_template目录下没有__init__.py，Python可能无法将其识别为可导入的包，这是常见的低级错误。

二、检查pyproject.toml的关键配置 #

以下是确保包被正确打包的核心配置项，对照修改你的文件：

1. 包的包含规则 #

确保[project]字段中明确指定要打包的包，或通过自动发现配置覆盖：

[project]
name = "python3-template"
version = "0.1.0"
# 方式1：显式指定包名
packages = ["python3_template"]
# 方式2：自动发现当前目录下的所有包（推荐）
# [tool.setuptools.packages.find]
# where = ["."]

[project.scripts]
# 确保入口路径正确：如果run()在__init__.py中则用下面的写法；如果在main.py中则写"python3_template.main:run"
python3-template = "python3_template:run"

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

2. 验证配置有效性 #

先安装开发版测试配置是否正确：

pip install -e .

如果安装后能在任意目录下执行python3-template或导入python3_template，说明配置没问题；如果还是报错，继续排查。

三、排查wheel包的实际内容 #

构建wheel后，手动解压检查包结构是否正确：

1. 找到生成的wheel文件（默认在dist/目录下，如python3_template-0.1.0-py3-none-any.whl）
2. 用解压工具打开，确认顶层目录下存在python3_template/文件夹，且包含所有模块文件

如果解压后没有python3_template目录，说明打包时未包含该包，回到pyproject.toml检查packages配置。

四、确认环境一致性 #

• 执行which python3-template（Linux/macOS）或where python3-template（Windows），查看控制台脚本的路径，确认其关联的Python解释器与安装wheel时使用的是同一个（比如是否激活了虚拟环境）。
• 避免混用不同版本的Python（如python和python3），确保安装和运行用的是同一环境。

五、修复入口路径（如果run()不在__init__.py中） #

如果run()函数定义在python3_template/main.py中，需要修改[project.scripts]的路径：

[project.scripts]
python3-template = "python3_template.main:run"

同时在__init__.py中可选择性导入run，方便交互式使用：

from .main import run

最终验证步骤 #

1. 清理旧的安装包：pip uninstall -y python3-template
2. 重新构建wheel：python -m build --wheel
3. 安装新wheel：pip install dist/python3_template-0.1.0-py3-none-any.whl
4. 在任意目录执行python3-template或启动Python交互环境测试导入：

   import python3_template
   python3_template.run()
   

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