本地pip安装的Python包无法导入，求问题排查与解决

我严格按照官方文档、两本书籍及三个第三方教程的步骤创建并安装Python包，却始终无法导入，也找不到能解决问题的有效错误信息，恳请帮忙定位问题。

文件夹结构 #

src/
    __init__.py
    stuff.py
pyproject.toml

文件内容 #

__init__.py #

from stuff import *

stuff.py #

def dance() -> int:
    return 20

pyproject.toml #

[project]
name = "applesauce"
version = "0.0.1"
authors = [
{ name="Jane Doe", email="janedoe@example.com" },
]
description = "A test package"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://example.com/applesauce"
"Bug Tracker" = "https://example.com/applesauce/issues"

操作步骤 #

安装过程显示成功：

$ python -m pip install ~/applesauce

Installing build dependencies ... done
Getting requirements to build wheel ... done
Installing backend dependencies ... done
Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: applesauce
Building wheel for applesauce (pyproject.toml) ... done
Created wheel for applesauce: filename=applesauce-0.0.1-py3-none-any.whl size=1539 sha256=7aad1073d884974ff119dc4ac04b40a2daaecf6b3b45f34b3de5bfd55cfa4c67
Stored in directory: /tmp/pip-ephem-wheel-cache-an0mxg3o/wheels/a2/5b/ce/6e4327bbc99ccd453f25abb9e6258bd6d475ba061d0377c48f
Successfully built applesauce
Installing collected packages: applesauce
Successfully installed applesauce-0.0.1

但执行导入时报错：

$ python -c "import applesauce"

Traceback (most recent call last):
    File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'applesauce'

我已尝试以下方法，均无效：

• 使用python -m build生成whl文件后安装
• 改用setuptools配置
• 在Windows环境下测试
• 可编辑模式安装（pip install -e）
• 使用绝对/相对路径安装
• 添加--no-index参数安装

问题根源 #

你的pyproject.toml未指定包的实际位置，打包工具无法识别src目录下的内容需要作为applesauce包安装，导致安装后系统中没有生成可导入的applesauce模块。

解决方法 #

方法1：自动识别src目录（推荐） #

修改pyproject.toml，添加setuptools的包查找配置，让工具从src目录识别包：

[project]
# 保留原有的project配置内容不变

[tool.setuptools.packages.find]
where = ["src"]

方法2：手动指定包路径 #

如果不想用自动查找，可手动指定包名与对应目录：

[project]
# 保留原有的project配置内容不变

[tool.setuptools]
packages = ["applesauce"]
package-dir = {"applesauce" = "src"}

方法3：调整文件夹结构 #

将src目录重命名为applesauce，让打包工具自动识别：

applesauce/
    __init__.py
    stuff.py
pyproject.toml

验证步骤 #

修改配置或结构后，重新强制安装包：

pip install --force-reinstall ~/applesauce

然后执行导入测试：

python -c "import applesauce; print(applesauce.dance())"

若输出20，则问题解决。

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