新一代python项目管理：uv (有水准)

一、认识 uv重塑 Python 包管理体验uv 是由 Astral 公司Ruff 代码检查工具的开发商用 Rust 语言编写的现代化 Python 包管理器和项目管理工具。它的出现彻底改变了 Python 生态中安装慢、工具散、环境乱的痛点一个工具就能替代 pip、venv、pip-tools、Poetry、PDM、pipx 等多款工具的核心功能。1.1 uv 的核心优势极致速度基于 Rust 编写依赖解析和安装速度比传统 pip 快 10-100 倍功能一体化包管理、虚拟环境、Python 版本管理、项目脚手架一站式解决全局缓存跨项目共享依赖缓存避免重复下载节省磁盘空间标准兼容完全遵循 PEP 标准原生支持 pyproject.toml无缝迁移现有项目锁文件机制内置 uv.lock 精确锁定依赖版本保证环境可复现1.2 安装 uvuv 的安装非常简单各平台通用一行命令即可macOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|shWindowsPowerShellpowershell-cirm https://astral.sh/uv/install.ps1 | iex通过包管理器安装pipinstalluv安装完成后验证版本uv--version# 输出示例uv 0.4.17 (a1b2c3d 2026-02-08)1.3 快速体验# 创建一个新项目使用Python 3.12 虚拟环境如果本地没有 3.12uv 会自动下载uv init my_project--python3.12# 可近似认为 相当于 以下命令的 简写# uv init my_project# uv venv --python 3.12# uv python pin 3.12# 安装依赖uv add requests# 不要用下面的 方式 安装依赖# uv pip install requests 该方式 不会 同步版本文件 的记录# uv run 运行 py 代码uv run python main.py二、项目管理核心命令2.1 uv init初始化项目uv init用于快速创建一个标准的 Python 项目结构自动生成 pyproject.toml、示例代码、Git 仓库等基础设施。基本语法uv init[OPTIONS][PATH]常用参数参数说明--name NAME指定项目名称默认使用目录名--python VERSION指定项目 Python 版本如3.12--lib创建库项目生成 src 目录结构--app创建应用项目默认生成 main.py--no-readme不生成 README.md--no-git不初始化 Git 仓库--no-vcs完全跳过版本控制系统初始化实战示例# 1. 在当前目录创建项目uv init# 2. 创建一个名为 fastapi-demo 的应用项目指定 Python 3.12uv init fastapi-demo--python3.12# 3. 创建一个库项目适合发布到 PyPIuv init my-library--lib# 4. 极简初始化不生成 Git 和 READMEuv init simple-project --no-git --no-readme执行uv init fastapi-demo后项目结构如下fastapi-demo/ ├── .git/ # Git 仓库 ├── .gitignore # Python 标准忽略规则 ├── .python-version # Python 版本声明文件 ├── README.md # 项目说明文档 ├── hello.py # 示例入口文件 └── pyproject.toml # 项目配置与依赖声明生成的 pyproject.toml 内容示例[project] name fastapi-demo version 0.1.0 description Add your description here requires-python 3.12 dependencies [] [build-system] requires [hatchling] build-backend hatchling.build 小提示首次执行uv sync或uv run后会自动创建.venv虚拟环境目录和uv.lock锁文件。2.2 uv add添加依赖uv add是最常用的命令之一用于向项目添加依赖包。它会自动更新 pyproject.toml、重新解析依赖、更新锁文件并同步安装到虚拟环境。基本语法uvadd[OPTIONS]PACKAGES...常用参数参数说明--dev添加为开发依赖对应[tool.uv.dev-dependencies]--group GROUP添加到指定依赖组如docs、test--version VERSION指定版本约束如2.31.0--editable/-e以可编辑模式安装本地开发包--no-sync只更新配置和锁文件不安装到虚拟环境--frozen严格按照现有锁文件操作不更新版本-r FILE从 requirements.txt 文件批量添加实战示例# 1. 添加单个生产依赖uvaddrequests# 2. 添加多个依赖包uvaddfastapi uvicorn pydantic# 3. 指定精确版本uvaddrequests2.32.3# 4. 指定版本范围uvaddhttpx0.27.0,0.28# 5. 添加开发依赖pytest、ruff 等测试/工具类uvadd--devpytest ruff mypy# 6. 添加到自定义依赖组uvadd--groupdocs mkdocs mkdocs-material# 7. 从 Git 仓库安装uvaddgithttps://github.com/psf/requests.git# 8. 从 Git 指定分支/标签安装uvaddgithttps://github.com/psf/requests.gitv2.32.3# 9. 从本地目录以可编辑模式安装uvadd-e../my-local-package# 10. 从 requirements.txt 批量导入uvadd-rrequirements.txt执行uv add fastapi uvicorn后pyproject.toml 会自动更新[project] name fastapi-demo version 0.1.0 requires-python 3.12 dependencies [ fastapi0.115.0, uvicorn0.30.0, ]2.3 uv remove移除依赖uv remove用于从项目中移除依赖包同步更新配置文件、锁文件和虚拟环境。基本语法uv remove[OPTIONS]PACKAGES...常用参数参数说明--dev从开发依赖中移除--group GROUP从指定依赖组移除--no-sync只更新配置不卸载虚拟环境中的包--frozen不重新解析锁文件实战示例# 1. 移除单个依赖uv remove requests# 2. 移除多个依赖uv remove fastapi uvicorn# 3. 移除开发依赖uv remove--devpytest# 4. 从自定义组移除uv remove--groupdocs mkdocs⚠️ 注意如果依赖包是通过uv pip install手动安装的uv remove不会将其卸载它只管理 pyproject.toml 中声明的依赖。2.4 uv sync同步项目环境uv sync是项目环境同步的核心命令它会根据 pyproject.toml 和 uv.lock 安装所有依赖确保本地环境与锁文件完全一致。基本语法uvsync[OPTIONS]常用参数参数说明--frozen严格按照锁文件安装锁文件过时则报错CI/CD 必备--no-dev不安装开发依赖生产环境部署用--group GROUP额外安装指定依赖组--all-groups安装所有依赖组--reinstall强制重新安装所有包--reinstall-package PKG强制重新安装指定包实战示例# 1. 完整同步安装生产开发依赖uvsync# 2. 生产环境部署只装生产依赖uvsync--no-dev# 3. CI/CD 环境严格锁定版本uvsync--frozen# 4. 同步时额外安装 docs 组uvsync--groupdocs# 5. 强制重装某个包解决包损坏问题uvsync--reinstall-package requests# 6. 全新重装所有依赖uvsync--reinstall CI/CD 最佳实践在流水线中务必使用uv sync --frozen它会确保完全按照 uv.lock 安装任何依赖变动都会导致构建失败从而保证环境一致性。2.5 uv lock生成/更新锁文件uv lock用于解析所有依赖并生成 uv.lock 锁文件锁定每个包的精确版本和哈希值确保跨环境的可复现性。基本语法uv lock[OPTIONS]常用参数参数说明--upgrade升级所有依赖到最新兼容版本--upgrade-package PKG升级指定包到最新版本--refresh刷新已有的锁文件不改变版本只更新元数据实战示例# 1. 生成或更新锁文件uv lock# 2. 升级所有依赖到最新兼容版本uv lock--upgrade# 3. 只升级 requests 包uv lock --upgrade-package requests# 4. 同时升级多个包uv lock --upgrade-package requests --upgrade-package httpx 锁文件原理uv.lock 记录了每个依赖的精确版本、下载 URL、哈希校验值以及完整的依赖树关系。建议将 uv.lock 提交到 Git 仓库团队成员和部署环境都能得到完全一致的依赖。三、运行与环境命令3.1 uv run在虚拟环境中执行命令uv run可以在项目的虚拟环境中执行任意命令或脚本无需手动激活虚拟环境是日常开发最高频的命令之一。基本语法uv run[OPTIONS]COMMAND[ARGS]...常用参数参数说明--with PKG临时注入额外的包再运行--no-sync运行前不自动同步环境--python VERSION指定 Python 版本运行实战示例# 1. 运行 Python 脚本uv run python main.py# 2. 运行项目内的命令行工具uv run pytest tests/-vuv run ruff check src/ uv run uvicorn main:app--reload--port8000# 3. 临时带上额外包运行uv run--withipython ipython# 4. 直接执行模块uv run python-mhttp.server8000# 5. 指定 Python 版本运行uv run--python3.11python--version 实用技巧uv run会自动检测项目根目录即使你在子目录中执行也能正确找到虚拟环境。这比手动 source activate 方便太多。3.2 uv run 脚本执行如果 pyproject.toml 里定义了脚本入口[project.scripts] wtt your_package.main:main然后就可以 uv run wtt3.3 uv venv虚拟环境管理虽然 uv 项目模式下会自动管理虚拟环境但uv venv提供了手动创建和管理虚拟环境的能力兼容传统工作流。基本语法uv venv[OPTIONS][PATH]常用参数参数说明--python VERSION指定 Python 版本--prompt NAME设置虚拟环境提示符名称--system-site-packages允许访问系统包--seed预装 pip、setuptools、wheel实战示例# 1. 在当前目录创建 .venvuv venv# 2. 指定路径和 Python 版本uv venv .venv311--python3.11# 3. 创建时预装 pip兼容旧工具uv venv--seed# 4. 自定义提示符uv venv--promptmyproject创建后激活方式与标准 venv 一致# macOS / Linuxsource.venv/bin/activate# Windows.venv\Scripts\activate3.4 uv pythonPython 版本管理uv 内置了 Python 版本管理能力可以自动下载和管理多个 Python 版本无需额外安装 pyenv。常用子命令# 1. 列出已安装的 Python 版本uv python list# 2. 列出所有可安装的 Python 版本uv python list--all# 3. 安装指定 Python 版本uv pythoninstall3.12uv pythoninstall3.11.8# 4. 卸载 Python 版本uv python uninstall3.10# 5. 查找符合要求的 Pythonuv pythonfind3.11# 6. 显示 uv 使用的 Python 路径uv pythonwhich✨ 亮点uv 会自动下载官方 Python 发行版并管理在全局缓存中项目通过.python-version文件声明版本uv 自动匹配使用真正做到了声明即拥有。四、pip 兼容模式uv pip对于习惯了 pip 命令或需要维护传统 requirements.txt 项目的用户uv 提供了uv pip子命令完全兼容 pip 的接口但速度提升数十倍。4.1 常用 pip 兼容命令# 1. 安装包uv pipinstallrequests uv pipinstallrequests2.32.3 uv pipinstall-rrequirements.txt# 2. 升级包uv pipinstall--upgraderequests# 3. 卸载包uv pip uninstall requests# 4. 列出已安装的包uv pip list uv pip list--outdated# 查看可升级的包# 5. 冻结依赖uv pip freezerequirements.txt# 6. 显示包信息uv pip show requests# 7. 检查依赖完整性uv pip check4.2 pip 模式高级参数# 指定索引源国内镜像加速uv pipinstalltorch --index-url https://download.pytorch.org/whl/cu121# 使用额外索引源uv pipinstallpackage --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple# 从 requirements.txt 安装并严格锁定uv pipinstall-rrequirements.txt--strict 迁移建议如果你的项目还在用 requirements.txt可以先用uv pip享受速度提升再逐步迁移到 pyproject.toml uv.lock 的现代化项目管理模式。五、实用辅助命令5.1 uv tree查看依赖树uv tree以树形结构展示项目的完整依赖关系帮助你理解依赖传递和排查版本冲突。# 1. 显示完整依赖树uv tree# 2. 只显示生产依赖uv tree --no-dev# 3. 反向查找某个包被谁依赖uv tree--invertrequests# 4. 显示重复的包排查版本冲突uv tree--duplicates输出示例fastapi-demo v0.1.0 ├── fastapi v0.115.0 │ ├── pydantic v2.9.2 │ │ ├── annotated-types v0.7.0 │ │ ├── pydantic-core v2.23.4 │ │ └── typing-extensions v4.12.2 │ ├── starlette v0.38.6 │ │ └── anyio v4.6.0 │ │ ├── idna v3.10 │ │ └── sniffio v1.3.1 │ └── typing-extensions v4.12.2 └── uvicorn v0.30.6 ├── click v8.1.7 └── h11 v0.14.05.2 uv export导出依赖uv export可以将 uv.lock 导出为其他格式方便与传统工具或部署平台兼容。# 1. 导出为 requirements.txt 格式uvexportrequirements.txt# 2. 只导出生产依赖uvexport--no-devrequirements.txt# 3. 导出包含哈希校验增强安全性uvexport--hashesrequirements.txt# 4. 导出为 constraints 文件uvexport--formatconstraintsconstraints.txt5.3 uv cache缓存管理uv 的全局缓存是其高性能的核心机制uv cache命令可以查看和管理缓存。# 1. 查看缓存目录位置uv cachedir# 2. 查看缓存统计信息uv cache info# 3. 清理无用缓存自动清理过期和未使用的包uv cache prune# 4. 完全清空缓存uv cache clean# 5. 验证缓存完整性uv cache verify 缓存位置macOS/Linux:~/.cache/uvWindows:%LOCALAPPDATA%\uv\cacheCI/CD 环境中可以缓存这个目录大幅提升构建速度。5.4 uv tool全局工具管理uv tool类似 pipx用于安装和管理全局 Python 命令行工具每个工具拥有独立的虚拟环境互不干扰。# 1. 安装全局工具uv toolinstallruff uv toolinstallipython uv toolinstallpoetry# 2. 列出已安装的工具uv tool list# 3. 升级工具uv tool upgrade ruff# 4. 卸载工具uv tool uninstall ruff# 5. 运行已安装的工具uv tool run ruff--version5.5 uv audit安全审计uv audit用于扫描项目依赖中的已知安全漏洞帮助你及时发现和修复风险。# 1. 审计所有依赖uv audit# 2. 只审计生产依赖uv audit --no-dev# 3. 输出 JSON 格式便于集成 CIuv audit--formatjson六、构建与发布6.1 uv build构建包uv build可以将项目构建为源码分发包sdist和 wheel 包无需额外安装 build 工具。# 1. 构建 sdist 和 wheeluv build# 2. 只构建 wheeluv build--wheel# 3. 只构建源码包uv build--sdist# 4. 指定输出目录uv build--outdist/6.2 uv publish发布到 PyPI# 1. 发布到 PyPI需要用户名和密码uv publish# 2. 使用 API Token 发布uv publish--tokenpypi-xxxxxxxxxx# 3. 发布到测试环境uv publish --index-url https://test.pypi.org/legacy/七、高级配置与最佳实践7.1 配置国内镜像源默认从 PyPI 下载在国内速度较慢可以配置清华镜像源加速。在项目根目录创建uv.toml或在 pyproject.toml 中配置# pyproject.toml [[tool.uv.index]] name tsinghua url https://pypi.tuna.tsinghua.edu.cn/simple default true或者通过环境变量全局配置exportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple7.2 多索引源与专用包对于 PyTorch、TensorFlow 等有专用索引的包可以单独配置[[tool.uv.index]] name pytorch-cu121 url https://download.pytorch.org/whl/cu121 explicit true # 只用于明确指定的包 [tool.uv.sources] torch { index pytorch-cu121 } torchvision { index pytorch-cu121 }7.3 CI/CD 最佳实践GitHub Actions 中使用 uv 的典型配置-name:Install uvuses:astral-sh/setup-uvv3-name:Sync dependenciesrun:uv sync--frozen-name:Run testsrun:uv run pytest关键要点使用--frozen确保严格按照锁文件安装缓存~/.cache/uv目录加速后续构建所有命令通过uv run执行确保环境一致7.4 从 Poetry / PDM 迁移迁移到 uv 非常简单保留 pyproject.toml 中的依赖声明删除旧的锁文件poetry.lock / pdm.lock运行uv lock生成 uv.lock运行uv sync安装依赖更新 .gitignore添加.venv7.5 常用环境变量变量名作用UV_CACHE_DIR自定义缓存目录UV_INDEX_URL默认 PyPI 索引地址UV_NO_CACHE禁用缓存设为 1UV_PYTHON指定默认 Python 解释器UV_FROZEN强制 frozen 模式八、性能为什么这么快原理简析uv 之所以比传统 pip 快几十上百倍核心在于以下几点技术优化Rust 语言实现零成本抽象、内存安全、原生并发比 Python 解释器执行快得多全局共享缓存所有项目共享同一份下载缓存和 wheel 缓存避免重复下载和编译并行下载与安装充分利用多核 CPU同时下载和安装多个包增量依赖解析基于现代 SAT 求解算法依赖解析速度数量级提升二进制 wheel 优先优先使用预编译 wheel避免本地编译耗时九、常见问题与技巧Q: uv 和 pip 可以混用吗A: 可以但不推荐。uv 完全兼容 venv 标准pip 安装的包 uv 能识别。但混用会导致锁文件和实际环境不一致建议统一使用 uv 管理。Q: uv.lock 需要提交到 Git 吗A: 应用项目强烈建议提交保证团队和部署环境一致库项目Library可选通常不提交让使用者自己解析。Q: 可以离线使用吗A: 可以。只要缓存中有对应包加上--offline参数即可完全离线安装。Q: uv 支持 conda 吗A: uv 不管理 conda 包但可以和 conda 环境共存。如果只是 Python 包管理uv 完全可以替代 conda。Q: 如何查看某个命令的详细帮助A: 使用uv help 命令例如uv help add会列出所有参数和说明。十、命令速查表场景命令新建项目uv init my-project添加依赖uv add requests添加开发依赖uv add --dev pytest同步环境uv syncCI 严格同步uv sync --frozen运行脚本uv run python main.py运行测试uv run pytest升级所有依赖uv lock --upgrade查看依赖树uv tree安装全局工具uv tool install ruff安装 Pythonuv python install 3.12清理缓存uv cache prune结语uv 代表了 Python 包管理的下一代方向极致的性能、统一的体验、标准的兼容。从简单的脚本项目到复杂的生产级应用uv 都能提供流畅高效的开发体验。掌握本文介绍的这些核心命令和参数足以覆盖 95% 以上的日常开发场景。建议从现有项目开始尝试先用uv pip感受速度提升再逐步迁移到完整的项目管理模式。一旦习惯了 uv 的速度和便利就很难再回到传统的 pip 工作流了。