无法导入自制Python包：ModuleNotFoundError: No module named 'fasterprimes'

核心错误点 #

你碰到的ModuleNotFoundError: No module named 'fasterprimes'以及无法导入pkgname的问题，根源在这几个地方：

1. __init__.py的导入逻辑完全错误 #

你手动添加sys.path.append("./subfoldername")的做法在包安装后根本行不通：

• 包安装后会被放到Python的site-packages目录，本地开发时的相对路径./subfoldername在这个环境下不存在，自然找不到模块。
• 正确的做法是用相对导入或者基于包结构的绝对导入，完全不需要修改sys.path。

把./gitrepo/__init__.py改成下面这样：

# 推荐用相对导入，符合Python包规范
from .subfoldername import abc as fast, abc_alternate_ways as alternate

__all__ = ["fast", "alternate"]

或者用绝对导入（基于最终的包名）：

from pkgname.subfoldername import abc as fast, abc_alternate_ways as alternate

__all__ = ["fast", "alternate"]

2. 包名与实际目录名不匹配 #

你的pyproject.toml里写的包名是pkgname，但实际的根包目录是gitrepo——这会导致安装后，Python识别的包是gitrepo而非pkgname，除非你明确做了目录映射。

解决方法二选一：

• 直接把gitrepo目录改名为pkgname，和配置里的name保持一致；
• 或者在pyproject.toml里添加目录映射配置：

[tool.setuptools.package-dir]
pkgname = "gitrepo"

3. setuptools未正确识别子包 #

你的pyproject.toml没有告诉setuptools要打包哪些内容，导致子包subfoldername可能没被正确包含进去。

在pyproject.toml里添加包发现配置：

[tool.setuptools.packages]
find = {}

这样setuptools会自动扫描所有包含__init__.py的目录作为包的一部分。

4. 关于fasterprimes的报错 #

报错里提到的fasterprimes要么是你导入时手滑写错了包名（比如把pkgname写成了这个），要么是你的代码里有其他地方导入了这个不存在的模块，仔细检查你的导入语句就行。

修复步骤 #

1. 修正gitrepo/__init__.py的导入代码，删掉sys.path相关内容；
2. 对齐包名和目录名，或者添加package-dir映射；
3. 在pyproject.toml里添加包发现配置；
4. 重新安装：先卸载旧版本pip uninstall pkgname，然后到项目根目录执行pip install .重新构建安装。

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