uv不是pip加速版，而是绕过setup.py执行、依赖串行解析和重复下载的全新工具；它不执行构建，遇无预编译wheel时会回退PEP 517构建，导致卡在Building；需检查wheel兼容性、用--no-build跳过构建、升级包版本、迁移到pyproject.toml以发挥其并行下载与硬链接缓存优势。

uv 不是 pip 的加速版，它绕过了 setup.py 执行、依赖链串行解析和重复下载这三道传统瓶颈——你得先理解它“不做什么”，才能用好它“做了什么”。

为什么 uv install 有时还是卡在 Building xxx

常见错误现象：Failed to build numpy==1.19.5、ModuleNotFoundError: No module named 'distutils'、输出里反复出现 Building wheel for ...。

根本原因不是 uv 慢了，而是你在装一个不兼容当前 Python 版本、且没有预编译 .whl 的包。uv 本身不执行构建，但它会 fallback 到 PEP 517 构建流程（调用 setuptools.build_meta），这时就退化成和 pip 类似的行为。

• 检查包是否提供对应平台的 wheel：访问 PyPI 页面，确认有 numpy-*.cp312-win_amd64.whl 这类文件（Windows + Python 3.12）
• 强制跳过源码构建：加 --no-build 参数，uv 就只找 wheel，找不到直接报错，不尝试编译
• 升级包版本：比如 numpy 在 Python 3.13 下必然失败，改用 numpy>1.24 即可避开 distutils 移除问题
• 旧项目未迁移到 pyproject.toml：如果项目仍用 setup.py，uv 无法静态读取依赖，必须下载后执行构建脚本——这是速度下降的主因

uv.lock 文件到底锁了什么

uv.lock 不是 requirements.txt 的简单版本号快照，它是完整解析后的依赖图快照，包含每个包的 exact version、wheel URL、hash、以及它所声明的全部传递依赖（transitive dependencies）。

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• 它默认不区分 dev/prod，除非你用 uv add --group dev pytest 显式分组，否则所有依赖都进同一个 lock 图
• 修改 pyproject.toml 后运行 uv sync，uv 会重算整个图并更新 uv.lock；而 pip install -r requirements.txt 只按文本顺序装，不验证图一致性
• CI 环境中应提交 uv.lock 并用 uv sync 而非 uv pip install，前者跳过求解器直接复用 lock，更稳定也更快
• 不要手动编辑 uv.lock：它的结构是二进制序列化的 TOML-like 格式，人工改极易破坏校验和

如何让 uv 真正“跳过网络”做离线安装

uv 的缓存（~/.cache/uv）默认只在本机生效，且包含元数据和解析结果，但 uv pip install 默认仍会发起 HEAD 请求校验包是否变更。要彻底离线，必须组合使用两个机制：

• 先用 uv pip download --python-version 3.12 -r requirements.txt -o wheels/ 把所有 wheel 和 uv.lock 下载到本地目录
• 再用 uv pip install --find-links wheels/ --no-index --python-version 3.12 -r requirements.txt，其中 --no-index 关闭 PyPI 查询，--find-links 指向本地 wheel 目录
• 注意：如果 requirements.txt 里有 -e . 或 git 依赖，uv pip download 无法处理，需提前用 uv venv + uv pip install -e . 构建好可复用的 wheel
• 企业内网可搭私有 index（如 devpi），配合 UV_INDEX_URL 环境变量，比纯离线更可持续

Python 版本管理不是 uv 的强项

uv 能通过 -p 3.12 指定解释器路径，也能用 uv python list 查已安装版本，但它**不负责安装或编译 Python 解释器本身**——这点常被误读。

• uv python install 3.12 实际调用的是 pyenv（macOS/Linux）或 pyenv-win（Windows），uv 只做封装和路径注册
• 如果你没装 pyenv，uv python install 会直接失败，报错 Failed to install Python: pyenv not found
• Windows 用户尤其注意：pyenv-win 需手动初始化，且默认不把 Python 安装到 %USERPROFILE%\AppData\Local\pyenv 以外的位置，uv 无法越权写入系统目录
• 真正需要多版本切换的场景，建议用 pyenv 管理解释器，用 uv venv -p $(pyenv which 3.12) 创建环境，分工明确

uv 的底层逻辑很干净：它只做三件事——解析声明式依赖、并行获取二进制产物、硬链接复用缓存。一旦你开始让它执行构建、下载源码、或管理解释器生命周期，就等于把它拖回传统工具的老路上。真正的进阶，是学会用 pyproject.toml 描述一切，让 uv 始终跑在它设计的高速轨道上。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！