pip install 成功却跑旧代码:打包层六个静默失败
上周改完 pyproject.toml 里一行 packages,本地 pip install . 返回 0,单元测试全绿。同事从构建产物装上同一份 wheel,import 直接抛 ModuleNotFoundError;另一位同事改完代码重新打包,装上去跑的仍是上一版逻辑。两次排查都花了半天,最后发现都不是「代码写错」,而是打包层把文件选错了、pip 把安装跳过了,而两者都返回 0。
我实际用 CPython 3.13.14、setuptools 80.9.0、pip 26.1.2 在 Windows 11 上搭了 12 个最小工程,把这几个「成功」逐个拆开,官方文档的说法与实测行为放在一起对照。本文不含任何联盟推广链接。
TL;DR:
packages = ["mypkg"]是精确清单,不递归。子包不会自动带上,wheel 里少文件,安装照样返回 0,直到import那一刻才炸。- 包目录之外的数据文件进不了 wheel。sdist 里明明有,
python -m build也不报错。 include-package-data在pyproject.toml下默认true,在setup.cfg下默认false。显式写成false会让包内数据文件一起消失,构建零警告。- 同名同版本的 wheel,内容改了 pip 也会跳过,只给一行提示,退出码 0。
--upgrade也没用,要--force-reinstall。 - 两个发行版共用一个顶层包时,卸载其中一个会把另一个的文件删掉,之后
import抛的是AttributeError而不是ImportError。
先把「成功」拆成两层
安装成功只说明 wheel 里的文件被解压进了 site-packages;运行成功才说明需要的文件都在、版本也是对的。这两层之间没有任何闸门:pip 不会替你检查 import 能不能走通,构建后端也不会替你检查「用户装完之后还缺什么」。
所以打包类问题有个共同形状:退出码 0、日志只有 Successfully,出错点全部推迟到运行期。下面六条都属于这个形状,另外两条是硬报错,反而好处理。
失败一:packages 列表只认你写下的那几个名字
src 布局,包下有一个子包 mypkg/sub/,pyproject.toml 里这样写:
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[project]
name = "demo-pkg"
version = "0.1.0"
[tool.setuptools]
package-dir = {"" = "src"}
packages = ["mypkg"]
构建出来的 wheel 只有 1,579 字节,解开只有 mypkg/__init__.py 和 mypkg/core.py,mypkg/sub/deep.py 不在里面。安装返回 0,Successfully installed demo-pkg-0.1.0,然后:
ModuleNotFoundError: No module named 'mypkg.sub'
[project.scripts] 指向 mypkg.sub.cli:main 时更隐蔽:入口点照常写进 entry_points.txt,命令行脚本照常生成,只有真正去执行时才在 from mypkg.sub.cli import main 这一行炸掉。
官方文档在讲 find 的 include / exclude 时把规则写得很直白:glob 必须匹配完整包名,util 能匹配 util/__init__.py,但匹配不到 util/files/__init__.py,要写成 util* 才行。packages 数组的语义比这更窄:它是一份清单,不是模式。
改成自动发现即可:
[tool.setuptools.packages.find]
where = ["src"]
include = ["mypkg*"]
namespaces = false
namespaces = false 的意思是只认有 __init__.py 的目录。默认是 true,会把所有没有 __init__.py 的目录也当成包扫进来,这一点在 flat-layout 下容易多收东西。
失败二:包目录之外的数据文件,sdist 有 wheel 没有
工程里有个 assets/table.json 放在包外面,MANIFEST.in 写了 include assets/*.json。python -m build 同时产出两个文件:
datapkg-0.2.0.tar.gz 1,335 B data/table.json: True assets/table.json: True
datapkg-0.2.0-py3-none-any.whl 1,581 B data/table.json: True assets/table.json: False
sdist 里有的东西,wheel 里不一定有。装完之后读那个文件:
FileNotFoundError: [Errno 2] No such file or directory: '...\assets\table.json'
官方 Data Files 文档的 Non-Package Data Files 一节把话说到尽头:egg 时代那套「平台数据目录」已经废弃,there is no supported facility to reliably retrieve these resources,PyPA 的建议是「运行期需要访问的数据文件一律放进包目录内部」。换句话说,包外数据文件不是配置没写对,而是这条路本身不受支持。
修法两步:把文件搬进 src/datapkg/data/,再用 importlib.resources 读,不要手拼 __file__ 相对路径——手拼路径在 zip 导入和可编辑安装下都可能指偏:
from importlib.resources import files
def load_table():
return files("datapkg.data").joinpath("table.json").read_text(encoding="utf-8")
files() 需要 Python 3.9 及以上,encoding 参数显式写上,别依赖默认编码。
失败三:include-package-data 有两套默认值
同一份工程,只在 pyproject.toml 里加一行 include-package-data = false:
include-package-data 未写: wheel 1,581 B,含 datapkg/data/table.json
include-package-data = false: wheel 1,393 B,不含该文件,构建零警告
安装照样返回 0,然后 load_table() 抛 FileNotFoundError,路径指向 site-packages\datapkg\data\table.json——文件从来没被打进 wheel。体积也从 1,581 字节掉到 1,393 字节,少了 11.9%,构建过程一句警告都没有。
默认值是分裂的。官方原文:The default value for tool.setuptools.include-package-data is true when projects are configured via pyproject.toml,从 v61.0.0 起生效;而 setup.cfg 与 setup.py 下 include_package_data 的默认值是 False,为了向后兼容一直没改。
进 wheel 的判定公式文档也给了:
(not exclude-package-data) and ((include-package-data and MANIFEST.in) or package-data)
所以 MANIFEST.in 不是「只管 sdist」。include-package-data 为真时,MANIFEST.in 匹配到的包内文件会一起进 wheel;为假时,光有 MANIFEST.in 也进不去。要从两个方向都稳,直接写 package-data 更省心,它不依赖 MANIFEST.in:
[tool.setuptools.package-data]
datapkg = ["data/*.json"]
失败四:同名同版本 wheel,pip 直接不装
这条最容易骗过人。改完代码,版本号没动,重新构建,文件名与上一次完全相同(quiet_demo-2.0.0-py3-none-any.whl)。再装一次,完整输出只有两行:
Processing .\dist\quiet_demo-2.0.0-py3-none-any.whl
quiet-demo is already installed with the same version as the provided wheel. Use --force-reinstall to force an installation of the wheel.
退出码 0,没有 error,没有 warning。import quiet 拿到的是 Q1——上一版。加 --upgrade 也一样,实测 rc=0 且代码不变。只有 --force-reinstall 才会把它装进去,之后才是 Q2。
对照组很有意思:同样改代码不升版本,用 pip install .(源码目录)会老老实实重建并重装,日志里能看到 Attempting uninstall 和 Successfully installed。差别在于源码目录每次都要现构建一个 wheel,而直接给一个 wheel 文件时,pip 先判「同名同版本已装」,判中就不动了。
所以「本地是好的,装上去是旧的」这类问题,先看发版号有没有递增。CI 里更稳的做法是每次构建带唯一本地版本号,或者发布步骤固定加 --force-reinstall。
失败五:两个发行版共用一个顶层包
dist-a 与 dist-b 是两个发行版,但都提供顶层包 shared/。先装 a 再装 b,site-packages/shared/ 里会出现三个文件:
__init__.py only_a.py only_b.py
import shared 拿到的是 B1——后装的那个覆盖了 __init__.py。接着卸载 dist-a:
Successfully uninstalled dist-a-1.0.0
site-packages/shared 剩余:__pycache__ only_b.py
pip list 仍然列出 dist-b 1.0.0
再 import shared,报的是:
AttributeError: module 'shared' has no attribute 'VALUE'
不是 ImportError,因为包目录还在、__init__.py 已经没了,Python 把它当成一个空的命名空间包。pip list 那边毫不知情,dist-b 还好端端地列着。
原因在卸载机制:pip 按发行版自己的 RECORD 删文件,而两个发行版的 RECORD 都声称拥有 shared/__init__.py,谁先卸载谁把它带走。避免办法只有一条:顶层包名与发行版名一一对应,一个发行版一个顶层包。真要共享顶层,得用 PEP 420 隐式命名空间,且各方的子目录不能重名。
硬报错一:flat-layout 两个顶层包直接拒绝构建
这反而是好事,它当场就炸。工程根目录下同时有 alpha/ 和 beta/ 两个包,只写了 [build-system]:
error: Multiple top-level packages discovered in a flat-layout: ['beta', 'alpha'].
官方文档的解释是防呆:setuptools will refuse to create distribution archives with multiple top-level packages or modules,目的是防止把维护脚本之类的目录误发出去。文档给的出路是 src-layout 或自定义发现。
这里有个容易忽略的前提:自动发现只在 packages 与 py-modules 都没配置时才启用。你只要写了其中一个,自动发现完全不发生——包括那个「多顶层包」的保护也一起消失,于是变成前面失败一那种静默漏文件。配置写一半比完全不写更危险。
另一个坑在 flat-layout 的默认排除表:tests、docs、scripts、build、dist、venv、env、requirements、tools、utils 这些目录名默认不参与发现。你把包命名成 utils/,它会被静默跳过,wheel 里就没有它。
硬报错二:没有 setuptools 的 venv 加 no-build-isolation
Python 3.12 起 venv 不再预装 setuptools。实测 3.13.14 新建的虚拟环境里:
setuptools: False
wheel: False
在这种环境里跑 pip install . --no-build-isolation,退出码 2,输出一大段 traceback,最后一行是:
pip._vendor.pyproject_hooks._impl.BackendUnavailable: Cannot import 'setuptools.build_meta'
报错文本里没有一句「请先安装 setuptools」,只有 BackendUnavailable 和一段 pyproject_hooks 的调用栈,很容易被当成 pip 坏了。修法二选一:
python -m pip install setuptools wheel
python -m pip install .
或者干脆去掉 --no-build-isolation,让 pip 自己建隔离环境装构建依赖。--no-build-isolation 的本意是「构建依赖我已经准备好了」,前提是你真的准备好了。
失败六:版本号的两个答案
pyproject.toml 写 version = "1.0.0",__init__.py 里又手写 __version__ = "0.9.9"。装完之后两个接口各说各话:
mypkg.__version__ = 0.9.9
metadata.version(...) = 1.0.0
两处都要维护,就一定会漏一处。要么把版本收进一处,让构建时读取:
[project]
dynamic = ["version"]
[tool.setuptools.dynamic]
version = {attr = "mypkg.__version__"}
要么干脆不在包里写 __version__,运行期统一用 importlib.metadata.version("demo-pkg") 读。前者的坑是 attr 走的是静态解析,__version__ 必须是字面量,用函数拼出来的字符串读不到。
可编辑安装到底改了什么
pip install -e . 装完,site-packages 里没有实体包目录,只有一个 .pth 文件,内容就是源码目录一行:
D:\work\shadow\src
效果是 sys.path 多了这一行,导入直接落到源码上。实测三件事:改已有文件立即生效;新增一个模块文件立即生效;新增一个顶层包也立即生效——这一条官方明说是副作用,by default an editable install will expose at least all the files that would be available in a regular installation,为了让你能边写边加模块,它可能多暴露一些本来不该有的文件。
哪些改动必须重装,官方 Limitations 也列了:新增依赖、改入口点、改元数据,都得重新 -e 一次。另外「包目录之外的文件在可编辑安装后是否可访问」官方明确不保证。
要更接近普通安装的行为,用 strict 模式:
python -m pip install -e . --config-settings editable_mode=strict
strict 模式会在 build/__editable__.* 下建一棵文件链接树,新加的文件不会被暴露。代价是这个目录不能删,删了导入就断。官方也提醒:editable 不是普通安装的完美替代,上线前一定要用真正的 wheel 在干净环境里跑一遍。
Troubleshooting:六个报错原文与修法
报错一 · Multiple top-level packages discovered in a flat-layout
现象:pip wheel . 在准备元数据阶段就失败,退出码 1。原因:flat-layout 下发现多个顶层包,setuptools 拒绝构建。修法:改 src-layout,或显式写 [tool.setuptools.packages.find] where = ["src"] 加 include。不要用「随手写一个 packages = [...]」来绕过,那会关掉自动发现,连带丢掉多顶层包保护。
报错二 · ModuleNotFoundError: No module named 'mypkg.sub'
现象:安装成功、import 顶层包正常,只有子包或子包里的入口点炸。原因:packages 清单里只写了 mypkg。修法:改成 packages.find 并给 include 加通配符;改完用 unzip -l dist/*.whl 数一遍文件。
报错三 · FileNotFoundError: No such file or directory: '...\datapkg\data\table.json'
现象:源码目录里跑得好好的,装完就找不到数据文件。原因:include-package-data = false,或文件在包目录之外。修法:文件搬进包内,配 package-data,读取改 importlib.resources.files()。
报错四 · BackendUnavailable: Cannot import 'setuptools.build_meta'
现象:--no-build-isolation 下退出码 2,一大段 traceback 里没有可读建议。原因:3.12 起的 venv 不预装 setuptools。修法:先 pip install setuptools wheel,或去掉 --no-build-isolation。
报错五 · AttributeError: module 'shared' has no attribute 'VALUE'
现象:卸载另一个包之后,import 不报 ImportError 而是 AttributeError。原因:两个发行版共用一个顶层包,卸载方把 __init__.py 删了。修法:查 site-packages 下该目录的文件归属,重装被破坏的那个包;根治靠一发行版一顶层包。
报错六 · quiet-demo is already installed with the same version as the provided wheel
现象:装完还是旧代码,退出码 0。原因:同名同版本 wheel 被跳过。修法:--force-reinstall;发版流程里保证版本号唯一。
发布前的三条清点
第一条,清点产物内容,别只看退出码。官方文档本身就建议这么做:
unzip -l dist/*.whl
tar tf dist/*.tar.gz
第二条,在干净环境里用 wheel 装一次再跑。可编辑安装和源码目录安装都会掩盖缺文件的问题,只有 wheel 装进空 venv 才是真实用户路径。
第三条,核对版本号只有一个来源。版本号重复会让 pip 静默跳过安装,而这一条在日志里只有一行提示,很容易被 CI 的 Successfully 关键字过滤掉。
顺带两个相邻话题:版本约束里 ~= 少写一位会锁死整个 patch 段,那篇拆的是版本号语义(PEP 440 版本约束实测);依赖装好之后还要查漏洞与 SBOM,那篇拆的是审计链路(pip-audit 与 SBOM)。pyproject.toml 本身也是 TOML,同一个值被解析成什么类型同样会咬人(配置文件默认值与类型)。
Q:pip install . 和 pip install dist/x.whl 为什么结果不一样?
A:前者每次都从源码目录现场构建一个新 wheel,所以同版本也会重装;后者拿到的是一个已经打好包的 wheel,pip 会先判「同名同版本是否已装」,判中就直接跳过,只留一行提示。
Q:src-layout 一定比 flat-layout 好吗?
A:对需要自动发现的工程,src-layout 更稳:根目录下的脚本、缓存目录不会被误收进发行包。代价是不能靠 PYTHONPATH=. 直接在项目根起 REPL,得用可编辑安装。flat-layout 更适合单包小工具。
Q:可编辑安装能当上线前验证吗?
A:不能。官方明确说 editable 不是普通安装的完美替代,它可能多暴露文件,也可能让包外文件不可访问。上线前至少用 wheel 在一个空 venv 里装一次,跑一遍入口点和数据文件读取。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。