从PyPI/TestPyPI安装自定义Python包后无法直接import导入问题

问题根因 #

你从PyPI安装的包出现双层导入问题，核心是构建的发布包包含了冗余的目录层级：site-packages目录下生成了没有__init__.py的外层package_name目录（即你看到的命名空间模块），实际包含代码的内层包被放到了site-packages/package_name/package_name/路径下。
开发模式pip install -e正常是因为该模式会直接把项目根目录加入Python搜索路径，内层package_name包直接暴露在路径下，无需额外层级即可导入。

解决步骤 #

1. 清理旧构建产物 #

每次打包前必须删除历史构建生成的缓存文件，避免旧错误产物被重复上传，在setup.py所在目录执行命令：

# Linux/Mac 环境
rm -rf build dist *.egg-info

# Windows 环境
rd /s /q build dist
del /s /q *.egg-info

2. 验证构建工作目录 #

必须在setup.py所在的目录执行打包、上传命令，不允许在该目录的上级路径执行构建操作，否则会把外层项目目录纳入包结构。

3. 调整setup.py配置（可选，如仍有问题可添加） #

如果按上述步骤操作后问题仍存在，可在setup.py中明确指定包路径映射：

from setuptools import setup, find_packages

setup(
  name = 'package_name',
  packages = find_packages(),
  package_dir = {'package_name': 'package_name'},
  version = '0.1.0',
  # 其余原有配置保持不变
)

4. 验证构建产物结构 #

重新执行构建命令：

python -m build

打开生成的dist目录，将.whl后缀改为.zip解压，确认解压后的package_name目录直接包含__init__.py、name.py等代码文件，不存在嵌套的第二层package_name目录。

5. 重新上传测试 #

确认结构正确后重新上传到TestPyPI，测试安装前先卸载本地旧版本：

pip uninstall -y package_name
pip install --index-url https://test.pypi.org/simple/ package_name

此时执行import package_name即可正常加载包。

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