uv install 报错依赖缺失典型表现为“ERROR: No matching distribution found for xxx”或“Resolution failed”，本质是uv解析锁文件或pyproject.toml时卡在包的版本/平台/构建约束；常见原因包括wheel与Python版本不匹配、缺少setuptools≥61.0等构建依赖、或传递依赖未预下载。

uv install 报错时依赖缺失的典型表现

执行 uv install 后出现类似 ERROR: No matching distribution found for xxx 或 Resolution failed，基本可判定是依赖树不完整。这不是 pip 那种“找不到包”的模糊提示，而是 uv 在解析锁文件或 pyproject.toml 时明确卡在某个包的版本/平台/构建约束上。常见诱因包括：本地 wheel 不匹配目标 Python 版本、缺少构建依赖（如 setuptools>=61.0）、或传递依赖未被预下载。

用 uv pip download 预检依赖完整性

离线或受限环境必须提前验证依赖是否齐备。核心命令是 uv pip download，它能暴露所有隐式依赖：

Python uv 0.12.20

Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具，支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64，解压后可使用 uv 命令。

下载

• 先在联网机器运行：uv pip download --platform manylinux2014_x86_64 --python-version 3.11 --only-binary=:all: -r requirements.txt -d ./wheels
• 检查 ./wheels/ 是否包含目标包及其全部 dist-info 目录（如 requests-2.31.0.dist-info/）
• 特别注意 pyproject.toml 中 [build-system.requires] 声明的构建工具（如 hatchling），它们必须也在 ./wheels 中，否则离线安装会失败

uv add 时依赖冲突的快速定位

执行 uv add requests 却报 Conflict with existing package，说明当前环境已有不兼容版本。此时不要直接删包：

• 用 uv pip show requests 查看已安装版本和来源（wheel 还是 sdist）
• 加 --dry-run 参数试运行：uv add requests==2.31.0 --dry-run，uv 会输出完整解析路径和冲突点
• 若冲突来自开发依赖，确认是否误用了 --dev；uv 对 [tool.uv.dev-dependencies] 和普通依赖的解析是隔离的

ldd / objdump 无法替代 uv 的依赖分析

Linux 下习惯用 ldd 或 objdump -x 查二进制库依赖，但这对 Python 包无效。uv 管理的是纯 Python 轮子或编译后扩展模块的元数据依赖，不是 ELF 动态链接。真正要查的是 wheel 的 metadata.json 中的 requires_dist 字段——而 uv pip download --verbose 会在终端打印这部分信息，比手动解压 wheel 更直接。