Windows下安装用户包后importlib.metadata.distributions未更新问题咨询

核心原因 #

这不是Python Bug，而是Python启动时的路径初始化机制导致的：

• Windows下的用户级site-packages路径（%APPDATA%\Python\PythonXY\site-packages）由site模块在Python进程启动时自动检测并添加到sys.path。
• 如果启动时该目录不存在，site模块不会将其加入sys.path；即使后续手动创建目录或通过pip安装包到该路径，当前Python进程的sys.path也不会自动更新，因此importlib.metadata.distributions()会忽略这个未被注册的路径。

提前创建目录也无效的原因是：Python启动时目录还不存在，site模块已经完成了sys.path的初始化，后续创建目录不会触发路径的自动刷新。

解决办法 #

在安装包后，手动触发路径注册和缓存刷新即可解决：

1. 获取并注册用户site-packages路径
   使用site.getusersitepackages()获取标准用户site-packages路径，通过site.addsitedir()将其添加到sys.path（该方法会自动处理目录下的.pth文件，比直接sys.path.append()更彻底）。

2. 清除导入缓存
   调用importlib.invalidate_caches()清除importlib的内部缓存，确保新路径下的包能被扫描到。

示例代码片段：

import site
import importlib
import importlib.metadata

# 获取用户site-packages路径
user_site_dir = site.getusersitepackages()

# 注册路径（如果尚未注册）
site.addsitedir(user_site_dir)

# 清除导入缓存
importlib.invalidate_caches()

# 现在可以正确获取包含新安装包的分发列表
installed_dists = list(importlib.metadata.distributions())

补充说明 #

• 如果你的脚本是通过调用外部pip进程完成安装（而非在当前Python进程内安装），上述步骤同样适用——因为外部pip进程的操作不会影响当前Python进程的sys.path。
• 若需在进程启动时就确保该路径被注册，可以在脚本开头加入路径检查和注册逻辑，避免后续重复操作。

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