importlib.metadata 版本怎么配置或排查

importlib.metadata 的版本不能在 version() 调用里配置。它读取的是当前 Python 解释器能够发现的、已安装 distribution 元数据中的 Version 字段。项目要配置版本，应在 pyproject.toml 或构建后端配置中声明；读取失败时，优先检查“用了哪个解释器、传入了哪个 distribution 名、安装元数据是否在该解释器的 sys.path 中”。

版本到底配置在哪里：先分清 distribution 和 import package

最容易误判的一点，是把“能 import 的名字”和“安装包名字”当成同一个对象。PyPA 将前者称为 import package，后者称为 distribution package；一个 distribution 可以提供多个导入包，反过来也可能出现命名空间包由多个 distribution 提供的情况。

因此下面的参数应写安装项目名，而不是盲猜模块名：

from importlib.metadata import PackageNotFoundError, version

try:
    # 这里传 distribution 名，返回已安装元数据里的 Version 字符串。
    current = version("demo-project")
except PackageNotFoundError:
    # 当前解释器找不到该 distribution 时，给出可定位的结果。
    current = "未安装或当前环境不可见"

print(current)

如果项目安装名是 demo-project，实际导入名可能是 demo_project。图1把这条边界画出来了：version() 经过发现机制读取安装目录中的 *.dist-info/METADATA，并不是读取 demo_project.__version__。

用 pyproject.toml 配置版本，再让安装元数据生效

现代项目通常把版本放在 pyproject.toml 的 project.version 中，或交给构建后端的动态版本机制。最小静态声明可以这样写：

[project]
name = "demo-project"
version = "1.4.0" # 版本会写入构建产物的 Core Metadata
description = "A small example package"

[build-system]
requires = ["setuptools>=61"] # 构建时提供项目元数据处理能力
build-backend = "setuptools.build_meta"

改动版本后，不要只在源码目录里执行读取代码。先重新安装当前项目，例如：

python -m pip install -e .
# 使用同一个 python 调 pip，避免 pip 和运行时属于不同虚拟环境

python -c 'from importlib.metadata import version; print(version("demo-project"))'
# 读取安装后的 distribution 版本，预期输出 1.4.0

开发环境使用 editable 安装时，代码文件可以直接映射到工作区，但版本仍来自安装元数据。若构建后端或安装动作没有刷新元数据，就可能出现源码已改、读取结果仍旧的现象。

PackageNotFoundError 和版本不一致怎么查

排查要把“运行时边界”锁死。下面四项信息应由同一个 python 命令采集，避免先用一个环境装包、再用另一个环境运行：

import sys
from importlib.metadata import distribution, version

name = "demo-project"
print("解释器:", sys.executable) # 确认实际运行的 Python
print("sys.path 首项:", sys.path[0]) # 观察模块与元数据搜索边界
print("版本:", version(name)) # 读取 distribution 的 Version
print("安装位置:", distribution(name).locate_file("")) # 定位该 distribution 的文件根目录

若这里报 PackageNotFoundError，依次检查：第一，安装命令是否使用了同一个 python -m pip；第二，参数是否为 distribution 名；第三，环境中是否真的存在对应的 .dist-info 或 .egg-info；第四，虚拟环境是否已经激活或显式使用了正确解释器。

可以把两种工具的结果放进一张小表，快速判断问题在哪一层：

别把 __version__ 当成唯一事实来源

__version__ 是模块作者约定的属性，importlib.metadata.version() 则读取安装 distribution 的标准元数据；两者可以一致，也可以因为发布、构建或导入路径混乱而不一致。若项目需要同时暴露二者，建议把版本只维护一份，并用测试断言它们一致。

最后记住一个边界：packages_distributions() 能帮助从顶层导入名反查 distribution，但 editable 安装可能没有完整的顶层名称映射，所以它适合辅助定位，不能替代对当前解释器和安装元数据的直接确认。

相关问题

importlib.metadata.version 传下划线还是连字符？

优先使用项目元数据中的 distribution 名。分发包名称在比较时通常会对大小写以及连字符、下划线、点号做规范化，但不要用改写名称来掩盖环境安装错误。

为什么 pip show 有版本，version() 却找不到？

最常见原因是两个命令调用了不同 Python。把 pip show 改成 python -m pip show demo-project，再用同一个 python 运行读取代码。

重新安装后仍然读到旧版本怎么办？

确认当前目录没有同名旧的 .dist-info，检查 editable 安装是否刷新元数据，并打印 distribution(name).locate_file("") 看实际命中位置。