uv 从入门到精通：Python 包管理的终极形态

uv 从入门到精通Python 包管理的终极形态全文约 8000 字建议收藏按章节循序渐进阅读。前言为什么你需要认识 uv先回答一个最直接的问题我已经用 pip venv 用得好好的为什么要换来看一组数据操作pipuv安装 NumPy Pandas无缓存~28 秒~2.3 秒安装相同依赖有缓存~12 秒~0.5 秒依赖解析复杂项目分钟级毫秒级某 AI 团队实测CI/CD 流水线从12 分钟缩短至 1 分 15 秒构建效率提升 89%。uv 由 Astral 公司Ruff 的作者用 Rust 编写目标是一把梭哈取代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等一众工具。一句话总结它快得不像 Python 工具但干的全是 Python 的活。第一章安装——三分钟搞定1.1 官方推荐安装方式macOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh或使用 wgetwget-qO- https://astral.sh/uv/install.sh|shWindows多种方式可选方式一推荐最简洁使用 Windows 原生包管理器wingetWindows 11 默认自带winget install--id astral-sh.uv这条命令会自动从微软商店下载安装 uv安装完成后即可在终端中使用uv命令。升级同样适用此命令。方式二PowerShell 脚本powershell-ExecutionPolicy ByPass-cirm https://astral.sh/uv/install.ps1 | iex也可以 pip 安装但不推荐因为失去了独立二进制的好处pipinstalluv1.2 验证安装uv--version# 输出类似: uv 0.11.x好的我已将 Windows 本地配置文件方式补充到1.3 节中现在该小节同时包含了**环境变量临时和全局配置文件持久**两种方式。以下是更新后的完整1.3 节内容您可以直接替换原文章中的对应部分1.3 国内镜像源配置加速必备为了提升包下载速度建议配置国内 PyPI 镜像。uv 支持两种配置方式按需选用。方式一环境变量当前会话生效适合临时测试或单次使用关闭终端即失效。Linux/macOSexportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple可将该行添加到~/.bashrc或~/.zshrc中以持久化但更推荐下面的配置文件方式。Windows PowerShell临时$env:UV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple方式二全局配置文件持久生效推荐配置一次所有uv命令自动生效无需重复设置。Windows创建或编辑配置文件C:\Users\你的用户名\AppData\Roaming\uv\uv.toml如果目录或文件不存在请手动创建写入以下内容[[index]] url https://pypi.tuna.tsinghua.edu.cn/simple default true保存后所有 uv 操作都会默认使用清华镜像源。Linux / macOS配置文件位于~/.config/uv/uv.toml内容与 Windows 完全相同。提示配置完成后可以运行uv debug查看当前生效的索引地址确认是否配置成功。如果使用winget安装配置文件路径不受影响同样有效。第二章核心概念——uv 到底能做什么uv 的功能可以划分为五个层次功能模块uv 实现方式替代的传统工具包管理uv pip installpip虚拟环境uv venvvirtualenv/venv依赖锁定uv.lock自动生成pip-tools requirements.txtPython 版本管理uv python installpyenv命令行工具管理uv tool install/uvxpipxuv 默认强制使用虚拟环境——这不是缺点是在帮你养成好习惯。第三章基础用法——5 个命令原地起飞对大多数人来说下面5 个命令覆盖了 90% 的日常使用场景。3.1 创建虚拟环境# 在当前目录创建 .venv默认名称uv venv# 指定名称uv venv my_env# 指定 Python 版本自动下载uv venv--python3.12uv 创建虚拟环境的速度在0.05 秒级别比python -m venv快一个数量级。3.2 安装包兼容 pip 语法# 安装到当前虚拟环境uv pipinstallnumpy pandas# 从 requirements.txt 安装uv pipinstall-rrequirements.txt# 安装到系统 Python不推荐但 CI 中可用uv pipinstallnumpy--system关键差异uv 默认只安装在虚拟环境中想装到系统需要显式加--system。3.3 运行脚本自动管理环境uv run python main.py当你执行uv run时uv 会自动检查/创建虚拟环境同步依赖如有pyproject.toml和uv.lock在环境中执行命令你不需要手动source activate这是 uv 和传统工具最大的体验差异。3.4 查看帮助uvhelpuv pip--help3.5 激活虚拟环境传统方式可选source.venv/bin/activate# Linux/macOS# .venv\Scripts\activate # Windows但有了uv run你几乎不需要手动激活。第四章项目级管理——像 Cargo 一样管理 Python 项目这是 uv 最精华的部分。它把 Python 项目管理提升到了Rust 的 Cargo 级别。4.1 初始化项目uv init myprojectcdmyproject生成的文件结构myproject/ ├── .gitignore ├── .python-version # 锁定 Python 版本 ├── README.md ├── main.py # 入口文件 └── pyproject.toml # 项目配置 依赖声明4.2 添加依赖uvaddrequests fastapi这会自动更新pyproject.toml中的依赖列表。pyproject.toml示例[project] name myproject version 0.1.0 dependencies [ requests2.31.0, fastapi0.104.0, ]4.3 锁定依赖生成 uv.lockuv lockuv lock会解析所有依赖的精确版本生成uv.lock文件。uv.lock不要手动编辑它是项目的依赖快照确保团队所有成员和生产环境安装完全一致的版本。4.4 同步环境uvsyncuv sync会根据uv.lock安装所有依赖到虚拟环境中。日常开发流程uv init projectcdproject uvaddflask sqlalchemy uv run python app.py# 自动 lock sync run4.5 升级依赖# 升级所有依赖到最新兼容版本uv lock--upgrade# 升级特定包uv lock --upgrade-package requests4.6 常用命令速查命令作用uv init初始化新项目uv add pkg添加依赖uv remove pkg移除依赖uv lock生成/更新锁文件uv sync同步环境到锁文件状态uv run cmd在项目环境中执行命令uv tree查看依赖树第五章Python 版本管理——告别 pyenvuv 内置了 Python 版本管理功能可以完全替代 pyenv。5.1 安装 Python 版本# 安装最新版本uv pythoninstall# 安装指定版本uv pythoninstall3.12uv pythoninstall3.113.12# 一次性安装多个# 安装 PyPyuv pythoninstallpypy3.105.2 查看可用/已安装版本uv python list5.3 自动下载uv 最智能的地方你不需要手动安装 Python。当你执行uv venv --python 3.12时如果系统没有 3.12uv 会自动下载安装。5.4 项目级 Python 版本锁定uv init生成的.python-version文件会锁定项目使用的 Python 版本团队成员 clone 后uv sync会自动使用正确的版本。第六章脚本运行——单文件也能优雅管理依赖uv 支持PEP 723内联依赖元数据你可以在 Python 文件头部声明依赖。6.1 在脚本中声明依赖# /// script# requires-python 3.9# dependencies [# pandas2.3.3,# ]# ///importpandasaspd data{City:[Tokyo,Delhi,Shanghai,Sao Paulo],Population_Millions:[37.3,32.0,28.5,22.4]}dfpd.DataFrame(data)print(df)6.2 直接运行uv run script.pyuv 会自动读取脚本头部的依赖声明创建临时环境并执行。6.3 用 uv add 添加脚本依赖uvadd--scriptscript.py pandas这会自动在脚本头部插入/更新依赖声明。适用场景数据分析脚本、一次性任务、分享给同事的独立脚本——不需要创建完整项目但依赖需要被管理。第七章工具管理——pipx 的完美替代uv tool和uvx用于管理 Python 命令行工具每个工具运行在独立的虚拟环境中。7.1 临时运行uvx# 一次性运行用完即焚uvx ruff check.uvx black--versionuvx--python3.10ruff# 指定 Python 版本uvx是uv tool run的别名。7.2 永久安装# 安装到 PATH全局可用uv toolinstallruff uv toolinstallblack# 之后直接使用ruff check.7.3 管理已安装的工具uv tool list# 列出已安装的工具uv tool uninstall ruff# 卸载对比 pipxuv 的 Rust 实现让工具安装和运行显著更快。第八章高级特性8.1 工作区Workspace——多包协同开发灵感来自 Rust 的 Cargo workspace适用于一个仓库包含多个关联 Python 包的场景。# 根目录 pyproject.toml [tool.uv.workspace] members [packages/*]工作区的特点每个包有自己的pyproject.toml共享一个uv.lock文件确保整个工作区依赖一致包之间可以互相引用editable 安装适用场景核心库 CLI 工具、微服务集合、大型 monorepo。8.2 缓存机制uv 使用激进的全局缓存来避免重复下载和构建依赖。缓存位置可配置Linux:~/.cache/uvmacOS:~/Library/Caches/uvWindows:%LOCALAPPDATA%\uv\cache清理缓存uv cache clean8.3 构建和发布包uv 支持将项目打包并发布到 PyPI# 构建分发包uv build# 发布到 PyPIuv publish# 或指定 tokenuv publish--tokenpypi-xxxxx8.4 与现有项目集成从 requirements.txt 迁移# 1. 初始化项目uv init# 2. 从 requirements.txt 添加依赖uvadd$(catrequirements.txt)# 3. 生成锁文件uv lock从 Poetry 迁移将pyproject.toml中的依赖迁移到[project.dependencies]运行uv lock生成锁文件更新 CI/CD 使用uv sync替代poetry install从 Conda 迁移# 导出 conda 环境conda list--explicitconda_env.txt# 提取 Python 包名用 uv add 逐个添加第九章与 pip 的兼容性uv 被设计为pip 和 pip-tools 工作流的 drop-in 替代品。9.1 兼容的命令几乎所有pip命令都可以直接加uv前缀使用uv pipinstallpkguv pip uninstallpkguv pip list uv pip freeze uv pip showpkguv pipinstall-rrequirements.txt9.2 已知差异场景pipuv默认安装位置当前激活的环境强制虚拟环境除非加--system依赖解析顺序解析慢并行解析快 10-100 倍多索引支持有限更灵活9.3 环境变量控制uv 会检测VIRTUAL_ENV环境变量exportVIRTUAL_ENV/path/to/venv uv pipinstallnumpy# 安装到指定环境第十章实战场景速查场景 1新项目从零开始uv init my_apicdmy_api uvaddfastapi uvicorn uvadd--devpytest black# 开发依赖uv run uvicorn main:app--reload场景 2克隆团队项目后gitclonerepocdrepouvsync# 一键搞定创建环境 安装所有依赖uv run pytest# 直接跑测试场景 3跑一个数据分析脚本# script.py 头部声明了 pandas 依赖uv run script.py# 自动处理环境场景 4CI/CD 流水线追求极致速度# GitHub Actions 示例- name: Install uv run:curl-LsSfhttps://astral.sh/uv/install.sh|sh- name: Sync dependencies run: uvsync--frozen# 不更新锁文件直接用- name: Run tests run: uv run pytest场景 5安装全局 CLI 工具uv toolinstallruff uv toolinstallhttpie第十一章常见问题与避坑指南Q1uv 和 Poetry 怎么选uv 更快依赖解析比 Poetry 快8 倍uv 更轻单二进制 ~10MBPoetry 需要 Python 环境Poetry 更成熟插件生态更丰富打包发布流程更完善结论新项目无脑 uv已有 Poetry 项目可暂不迁移但新功能开发建议规划迁移Q2uv 能替代 conda 吗不能完全替代。conda 擅长管理非 Python 依赖CUDA、MKL、OpenBLAS。纯 Python 项目用 uv需要 CUDA 的深度学习项目用 conda uv 混合使用。Q3uv pip install和uv add有什么区别uv pip install只安装包不记录到pyproject.tomluv add安装包并写入pyproject.toml依赖列表日常开发用uv add临时调试用uv pip install。Q4缓存占空间怎么办uv cache clean# 清理所有缓存uv cache prune# 只清理未使用的缓存Q5–locked、–frozen、–no-sync 的区别选项行为--locked锁文件过期则报错不自动更新--frozen使用锁文件但不检查是否过期--no-sync不检查环境是否同步Q6winget 安装后 uv 命令找不到怎么办Windows 新增winget默认将程序安装在%LOCALAPPDATA%\Programs\uv\目录如果该目录不在 PATH 中可手动添加到系统环境变量。或重启终端后再次尝试通常 winget 会自动处理 PATH 注册。总结2026 年你应该用 uv你的情况建议新项目直接用 uv从uv init开始在用 venv pip渐进迁移先用uv pip替代pip再引入项目级管理在用 Poetry保持但新功能模块可以试用 uv数据科学需要 CUDAuv conda 混合使用CI/CD必须换 uv速度提升肉眼可见uv 不是又一个 Python 工具它是Python 工具链的范式转移。从 Rust 实现到强制虚拟环境从自动依赖解析到内联脚本依赖uv 在设计上解决了传统工具积累二十年的痛点。2026 年不用 uv约等于 2020 年不用黑屏终端。开始吧Windows 用户可以直接 winget 安装# macOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows (Windows 11 推荐)wingetinstall--idastral-sh.uv验证安装uv--versionHappy Coding! ⚡