如果你是一名 Python 开发者是否经历过这样的场景新项目启动花半天时间折腾venv、pip、requirements.txt结果因为依赖冲突或版本不兼容环境死活配不好团队协作时同事的代码在你本地跑不起来一句“我本地是好的”让你怀疑人生想尝试一个新工具链光是安装和配置就足以劝退。这些琐碎但高频的“环境管理”和“依赖管理”问题正在无声地消耗着开发者的创造力和效率。过去我们习惯了pipvirtualenv/venv的组合或者用conda管理科学计算环境用poetry或pipenv试图解决依赖锁定问题。但每个工具都有其局限pip慢且依赖解析能力弱conda生态与 PyPI 不完全互通poetry虽好但学习曲线和性能在大型项目上仍是挑战。有没有一个工具能集各家所长用极致的速度、简单的命令和可靠的结果一站式解决从 Python 版本管理、虚拟环境创建、依赖安装、依赖锁定到项目构建、发布的全部问题答案是有它就是uv。uv并非一个默默无闻的新玩具它由 Rust 编写出自Astral团队也是 Ruff 格式化器和 Linter 的创造者其设计目标就是成为“一个用 Rust 编写的极其快速的 Python 包安装器和解析器”。但经过快速发展今天的uv早已超越了一个“快速 pip 替代品”的范畴。它正在重新定义 Python 项目管理的体验用接近原生 Rust 的启动和运行速度提供从项目初始化到依赖管理、脚本运行、甚至跨平台发布的完整工作流。本文将带你彻底搞懂uv。我们不止介绍它是什么更会深入剖析它为什么能解决上述痛点它适合谁以及在实际使用中可能遇到的“坑”。你将获得一份从零开始、手把手的实战指南涵盖安装、核心命令、多项目管理、与现有工作流集成以及如何将其融入团队协作和 CI/CD 流程。如果你厌倦了 Python 生态中的工具碎片化和缓慢的依赖解析那么uv很可能就是你一直在寻找的答案。1. 为什么你需要关注 uv它解决了什么根本问题在深入技术细节前我们必须先回答一个核心问题在已有众多工具的 Python 生态中为什么uv值得你投入时间学习uv解决的并非一个“从无到有”的问题而是一个“从有到优”的问题。它的核心价值在于极致的性能与统一简洁的体验具体体现在三个维度1. 依赖解析与安装速度的“降维打击”传统pip在解析复杂依赖关系时可能耗时数分钟甚至更久尤其是在网络不佳或依赖树庞大时。uv利用 Rust 的高性能并发和更优的解析算法将这个过程缩短到秒级甚至毫秒级。这不仅仅是“快一点”而是将原本可能打断心流状态的等待时间彻底消除。2. 一体化工作流告别工具链缝合一个典型的 Python 项目开发流程可能涉及用pyenv或asdf管理 Python 版本用venv创建虚拟环境用pip安装依赖用pip-tools或poetry锁定依赖版本用pytest运行测试用build和twine打包发布。你需要记住不同工具的命令和配置。uv试图用一个二进制文件覆盖所有这些环节uv python install安装 Pythonuv venv创建环境uv pip install安装包uv run运行脚本或命令uv build和uv publish处理分发。这种一致性极大地降低了认知负担。3. 确定性与可复现性提升uv在依赖解析上更加严格和一致。它默认生成uv.lock锁文件类似于poetry.lock或Pipfile.lock确保在任何机器、任何时间安装的依赖版本完全一致。这对于团队协作和持续集成至关重要能有效杜绝“在我机器上能跑”的经典问题。那么uv 最适合谁追求效率的个体开发者无法忍受缓慢的pip install希望工具“快且省心”。需要维护多个项目的工程师快速在不同项目、不同 Python 版本间切换环境。团队技术负责人寻求为团队建立统一、高效、可复现的开发环境规范。CI/CD 流水线维护者需要极速安装依赖以缩短流水线运行时间。如果你属于以上任何一类那么继续阅读uv将很可能成为你的主力工具。2. uv 核心概念与工作原理要高效使用一个工具理解其设计哲学和核心概念是关键。uv虽然命令简单但其背后有几个重要的设计理念。2.1 uv 不是什么是什么uv 不是一个 Python 发行版。它不捆绑 Python 解释器而是帮你下载和管理官方版本的 Python。uv 不只是一个更快的 pip。虽然uv pip命令兼容并大幅加速了pip的工作但uv的野心是整个 Python 项目生命周期。uv 是一个用 Rust 编写的 Python 项目管理工具链。它通过单一二进制提供了 Python 安装、虚拟环境管理、依赖安装与锁定、脚本运行、项目打包等能力。2.2 核心组件解析uv的功能围绕几个核心子命令展开理解它们就理解了uv的全貌uv python: Python 解释器管理。可以从多个源官方构建、conda-forge 等下载、安装、列出和移除特定版本的 Python完全替代pyenv等工具。uv venv: 虚拟环境管理。创建、删除、激活虚拟环境。其创建的环境是标准的venv兼容环境任何能识别venv的工具如 IDE都能正常工作。uv pip: 依赖管理。提供与pip完全兼容的命令行接口但执行速度极快且依赖解析更可靠。它可以直接操作当前激活的虚拟环境也可以通过--python参数指定环境。uv run: 命令执行器。在指定项目的上下文中运行命令。它会自动识别项目根目录通过pyproject.toml等加载对应的虚拟环境然后执行命令。这是实现“一体化”体验的关键。uv sync: 依赖同步。根据pyproject.toml或requirements.txt以及可选的锁文件uv.lock将虚拟环境的依赖同步到指定状态。这是安装依赖的推荐方式因为它保证了确定性。uv lock: 生成锁文件。解析项目依赖并生成一个精确的uv.lock文件记录所有直接和间接依赖的确切版本。uv build/uv publish: 项目打包与发布。构建符合 PyPA 标准的源码分发包和 wheel 包并可发布到 PyPI。2.3 工作流程对比传统 vs. uv为了更直观地理解uv带来的改变我们对比一个常见任务“在新机器上搭建项目环境”的步骤传统流程以 pip venv 为例:检查/安装所需 Python 版本可能用到 pyenv。python -m venv .venv激活虚拟环境.venv\Scripts\activate或source .venv/bin/activate。pip install -r requirements.txt漫长等待。运行项目python main.py。uv 流程:uv python install 3.11如果尚未安装该版本。uv venv --python 3.11 .venv创建环境。uv sync读取pyproject.toml并极速安装所有依赖。运行项目uv run python main.py自动识别.venv并执行。可以看到uv将多个工具的命令统一到了自己的命名空间下并且第 3、4 步的速度和体验有质的提升。更重要的是uv run让你可以不显式激活环境直接运行命令这对于脚本编写和 CI/CD 尤其友好。3. 环境准备与安装 uvuv的安装极其简单它是一个独立的二进制文件无需 Python 环境即可运行。3.1 安装 uv在 Linux/macOS 上使用官方安装脚本是最快的方式。它会下载适合你系统的最新uv二进制文件。# 使用 curl curl -LsSf https://astral.sh/uv/install.sh | sh # 或者使用 wget wget -qO- https://astral.sh/uv/install.sh | sh安装后脚本会提示你将uv所在目录通常是$HOME/.cargo/bin添加到PATH环境变量中。按照提示操作或重启终端即可。在 Windows 上可以使用 PowerShell 安装脚本或者通过包管理器scoop安装。使用 PowerShell:powershell -c irm https://astral.sh/uv/install.ps1 | iex使用 Scoop:scoop install uv验证安装安装完成后在终端中运行以下命令确认安装成功并查看版本。uv --version你应该能看到类似uv 0.4.x (rustc 1.xx.x)的输出。3.2 安装 Python可选但推荐虽然uv可以复用系统已安装的 Python但为了环境隔离强烈建议使用uv python来管理项目专用的 Python 解释器。这能保证项目之间完全独立避免系统 Python 升级带来的影响。使用以下命令查看可安装的 Python 版本并安装一个# 列出所有可安装的 Python 版本 uv python list # 安装特定版本的 Python例如 3.11.9 uv python install 3.11.9 # 安装某个主要版本的最新版例如 3.12 系列的最新版 uv python install 3.12uv会将 Python 安装到其自身管理的目录下如~/.uv/toolchains不会干扰系统 Python。4. 核心工作流实战从零开始一个项目理论说再多不如动手一试。让我们用一个完整的例子演示如何使用uv管理一个 Python 项目的全生命周期。4.1 项目初始化与虚拟环境创建假设我们要创建一个名为my_uv_project的数据分析小项目。# 1. 创建项目目录并进入 mkdir my_uv_project cd my_uv_project # 2. 初始化一个 pyproject.toml 文件如果喜欢手动创建也可以 # 这里我们使用 uv init 来快速生成一个基础模板 uv init --lib # --lib 表示这是一个库项目对于应用可省略或使用 --app执行uv init后会在当前目录生成一个基础的pyproject.toml文件内容大致如下[project] name my_uv_project version 0.1.0 description authors [ {name Your Name, email youexample.com}, ] dependencies [] requires-python 3.8 readme README.md [build-system] requires [hatchling] build-backend hatchling.build接下来我们为这个项目创建一个独立的虚拟环境并指定使用 Python 3.11。# 3. 创建虚拟环境使用我们之前安装的 Python 3.11 uv venv --python 3.11 .venv这会在当前目录下创建一个名为.venv的虚拟环境文件夹。你不需要手动激活它uv的相关命令会自动识别和使用它。4.2 依赖管理安装、锁定与同步现在我们的项目需要pandas和requests库并且为了开发还需要pytest和black。方式一使用uv add(推荐)uv add命令会同时做两件事1) 将依赖添加到pyproject.toml的[project]dependencies或[tool.uv]dev-dependencies部分2) 立即安装它们到当前虚拟环境。# 添加生产依赖 uv add pandas requests # 添加开发依赖测试、格式化等 uv add --dev pytest black执行后你的pyproject.toml会自动更新[project] name my_uv_project version 0.1.0 description authors [ {name Your Name, email youexample.com}, ] dependencies [ pandas2.2,3, requests2.32,3, ] requires-python 3.8 readme README.md [build-system] requires [hatchling] build-backend hatchling.build [tool.uv] dev-dependencies [ pytest8.2,9, black24.4,25, ]同时依赖已经被安装到了.venv环境中。方式二使用uv sync如果你喜欢手动编辑pyproject.toml或者从现有项目只有pyproject.toml或requirements.txt开始可以使用uv sync来安装所有依赖。# 手动编辑 pyproject.toml 添加依赖后运行 uv sync # 如果还有开发依赖一并安装 uv sync --dev生成锁文件为了确保依赖树的确定性我们应该生成锁文件。uv lock这会创建一个uv.lock文件里面记录了pandas、requests、pytest、black以及它们所有间接依赖的精确版本和哈希值。这个文件应该被提交到版本控制系统如 Git中。这样其他协作者或 CI 系统运行uv sync时就能得到完全一致的依赖环境。4.3 运行你的代码与脚本传统方式需要先激活环境source .venv/bin/activate再运行python。uv run让你跳过激活步骤。假设我们有一个简单的脚本src/my_uv_project/analysis.py# 文件路径src/my_uv_project/analysis.py import pandas as pd import requests def fetch_and_analyze(): # 示例获取一些数据 resp requests.get(https://api.github.com/events) events resp.json() # 转换为 DataFrame 并简单分析 df pd.DataFrame(events)[:5] # 取前5条 print(df[[id, type, actor]].to_string()) return df if __name__ __main__: fetch_and_analyze()你可以直接用uv run来执行它# 运行 Python 脚本 uv run python src/my_uv_project/analysis.py # 运行模块 uv run -m my_uv_project.analysis # 运行通过 [project.scripts] 定义的命令行工具如果有 # uv run my-cli-commanduv run会自动发现项目根目录通过pyproject.toml找到关联的虚拟环境.venv并在该环境中执行命令。这意味着你可以在任何子目录下运行它无需关心当前 shell 的环境状态。对于开发任务比如运行测试或格式化代码同样方便# 运行 pytest uv run pytest # 使用 black 格式化代码 uv run black .4.4 项目构建与发布当项目开发完成需要打包分发时uv也能胜任。# 构建源码包和 wheel 包 uv build # 构建完成后会在 dist/ 目录下生成包文件。 # 你可以使用 uv publish 将其发布到 PyPI需要提前配置 token # uv publishuv build会读取pyproject.toml中的[build-system]配置使用指定的后端如hatchling、setuptools进行构建其行为与python -m build完全一致但通常更快。5. 进阶使用场景与技巧掌握了基础工作流后我们来看一些uv在真实开发中能大显身手的进阶场景。5.1 多项目管理与 Python 版本隔离你可能有项目 A 需要 Python 3.9项目 B 需要 Python 3.11项目 C 需要 Python 3.12 的最新特性。用uv管理起来非常清晰。# 为项目 A 创建 Python 3.9 环境 cd /path/to/project_a uv venv --python 3.9 .venv # 为项目 B 创建 Python 3.11 环境 cd /path/to/project_b uv venv --python 3.11 .venv # 为项目 C 安装并创建 Python 3.12 环境 cd /path/to/project_c uv python install 3.12 # 确保有 3.12 uv venv --python 3.12 .venv每个项目的.venv都绑定着特定的 Python 解释器。使用uv run时它会自动选择正确的环境完全无需手动切换。uv python list可以查看所有通过uv安装的 Python 版本。5.2 与现有项目requirements.txt集成很多老项目还在使用requirements.txt。uv对此有很好的支持。# 直接从 requirements.txt 安装极快 uv pip install -r requirements.txt # 将 requirements.txt 转换为 pyproject.toml 并生成锁文件 # 首先确保有 pyproject.toml可以是最简化的然后同步 uv sync --requirements-file requirements.txt # 或者在已有 pyproject.toml 的 [project] 部分添加 # dependencies [package1, package2] 后用 uv sync你也可以让uv同时处理requirements.txt和requirements-dev.txtuv sync --requirements-file requirements.txt --requirements-file requirements-dev.txt --dev5.3 在 CI/CD 中使用 uv在 GitHub Actions、GitLab CI 等环境中uv可以显著缩短流水线时间。以下是一个 GitHub Actions 的示例片段# .github/workflows/test.yml jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: astral-sh/setup-uvv3 # 官方提供的 Action with: python-version: 3.11 - run: uv sync --dev # 极速安装依赖 - run: uv run pytest # 运行测试由于uv sync的速度优势和缓存机制整个安装依赖的步骤可能比传统pip install快 10-100 倍这对于需要频繁运行的 CI 任务来说节省了大量时间和计算资源。5.4 使用 uv 运行任意命令uv run的强大之处在于它可以运行任何命令不仅仅是 Python 脚本。只要该命令存在于虚拟环境的bin或Scripts目录下。# 运行安装在虚拟环境里的 jupyter lab uv run jupyter lab # 运行 ipython uv run ipython # 运行通过 pipx 安装的全局工具如果配置了路径 # uv run --system some-global-tool6. 常见问题与排查思路即使工具设计得再优秀在实际使用中也可能遇到问题。下表总结了使用uv时常见的“坑”及其解决方法。问题现象可能原因排查方式解决方案uv: command not founduv未安装或未正确加入PATH。执行echo $PATH查看路径或尝试~/.cargo/bin/uv --version。1. 重新运行安装脚本。2. 根据安装成功后的提示将export PATH$HOME/.cargo/bin:$PATH添加到~/.bashrc或~/.zshrc并source。uv python install失败或极慢网络问题无法从默认源下载 Python 安装包。检查网络连接观察错误信息是否与下载相关。1. 使用代理或更换网络环境。2. 配置镜像源目前uv对 Python 安装的镜像支持在完善中可关注官方文档。3. 手动下载对应平台的 Python 安装包放入~/.uv/toolchains/cache目录。uv sync或uv add时解析依赖失败依赖声明存在冲突或 PyPI 索引暂时不可用。查看完整错误信息通常uv会给出详细的依赖冲突报告。1. 检查pyproject.toml中dependencies的版本范围是否过于严格或冲突。2. 尝试使用--resolutionlowest或--resolutionhighest来调整解析策略。3. 临时使用--no-cache禁用缓存重试。IDE如 VSCode, PyCharm无法识别uv创建的环境IDE 的 Python 解释器自动发现机制可能未扫描到.venv目录或路径问题。在 IDE 的设置中手动指定 Python 解释器路径。1.VSCode: 按CtrlShiftP输入 “Python: Select Interpreter”选择./.venv/bin/python。2.PyCharm:File - Settings - Project - Python Interpreter点击齿轮图标添加选择./.venv目录。uv run找不到命令1. 虚拟环境中未安装该命令。2. 当前目录不是项目根目录无pyproject.toml。3. 项目根目录下没有.venv。1. 确认命令是否已安装 (uv pip list)。2. 确认当前目录存在pyproject.toml。3. 确认.venv目录存在。1. 使用uv add或uv pip install安装对应包。2. 在项目根目录下执行或使用--project /path/to/project指定项目路径。3. 使用uv venv创建虚拟环境。锁文件uv.lock更新不及时直接使用uv pip install绕过了uv的依赖管理导致锁文件与真实环境不一致。比较uv.lock和uv pip freeze的输出。坚持使用uv add或uv sync来管理依赖避免手动使用uv pip install package。如需更新使用uv add package --upgrade或修改pyproject.toml后运行uv lock。与现有poetry/pipenv项目兼容项目已存在poetry.lock或Pipfile。uv目前主要原生支持pyproject.tomluv.lock或requirements.txt。1.渐进迁移继续用poetry管理依赖但可以用uv run来执行命令享受速度。2.完全迁移将poetry的依赖导出到requirements.txt再用uv sync接管。未来uv可能会增加对Pipfile等的直接支持。7. 最佳实践与工程建议将uv融入个人或团队的工作流遵循一些最佳实践能让收益最大化。将uv.lock纳入版本控制这是保证团队环境一致性的基石。每次依赖变更增、删、升级后都应运行uv lock更新锁文件并提交。CI 系统应使用uv sync --locked来严格安装锁文件中记录的版本。统一项目初始化模板为团队创建一个标准的pyproject.toml模板包含统一的元数据格式、构建后端配置、以及通过[tool.uv]部分预置的常用开发依赖如pytest,black,isort,mypy,ruff。新项目用uv init生成后在此基础上修改。在 CI/CD 中优先使用uv在 GitHub Actions、GitLab CI 等中使用astral-sh/setup-uv等官方 Action 或直接安装uv二进制。用uv sync --dev替代pip install -r requirements.txt和pip install -e .[dev]能大幅缩短流水线运行时间。利用uv run简化脚本和文档在项目的README.md或Makefile中使用uv run作为命令前缀。例如将“运行测试”的指令从复杂的“激活环境后运行 pytest”简化为uv run pytest。这降低了新成员的参与门槛。谨慎处理全局安装uv管理的 Python 和虚拟环境默认是项目本地的。避免使用uv pip install --system进行全局安装以免污染系统环境。如果需要全局工具考虑使用pipx。监控依赖更新定期使用uv pip list --outdated检查过时的依赖。升级时使用uv add package --upgrade来更新pyproject.toml并重新生成锁文件而不是直接uv pip install --upgrade。理解uv的边界uv目前主要聚焦于“项目管理”和“包管理”。对于更复杂的多环境管理如需要同时管理 Node.js、Go 等asdf仍是更好的选择。对于需要复杂发布流程或私有仓库特殊配置的项目可能仍需结合twine、flit等工具。uv的出现标志着 Python 工具链在追求“开发者体验”和“极致性能”上迈出了关键一步。它没有引入革命性的新概念而是通过 Rust 重写和精心的设计将现有最佳实践整合并加速到了一个全新的水平。对于个人开发者它是提升日常效率的利器对于团队它是建立标准化、高效能工程规范的强大助推器。开始尝试uv的成本很低只需安装一个二进制文件。不妨从下一个个人小项目开始或者在一个现有项目中试用uv run来运行测试和脚本亲身感受其速度与便捷。随着你对它的熟悉很可能会发现你已经回不去那个需要频繁激活环境、等待漫长pip install的时代了。
如果你是一名 Python 开发者是否经历过这样的场景新项目启动花半天时间折腾venv、pip、requirements.txt结果因为依赖冲突或版本不兼容环境死活配不好团队协作时同事的代码在你本地跑不起来一句“我本地是好的”让你怀疑人生想尝试一个新工具链光是安装和配置就足以劝退。这些琐碎但高频的“环境管理”和“依赖管理”问题正在无声地消耗着开发者的创造力和效率。过去我们习惯了pipvirtualenv/venv的组合或者用conda管理科学计算环境用poetry或pipenv试图解决依赖锁定问题。但每个工具都有其局限pip慢且依赖解析能力弱conda生态与 PyPI 不完全互通poetry虽好但学习曲线和性能在大型项目上仍是挑战。有没有一个工具能集各家所长用极致的速度、简单的命令和可靠的结果一站式解决从 Python 版本管理、虚拟环境创建、依赖安装、依赖锁定到项目构建、发布的全部问题答案是有它就是uv。uv并非一个默默无闻的新玩具它由 Rust 编写出自Astral团队也是 Ruff 格式化器和 Linter 的创造者其设计目标就是成为“一个用 Rust 编写的极其快速的 Python 包安装器和解析器”。但经过快速发展今天的uv早已超越了一个“快速 pip 替代品”的范畴。它正在重新定义 Python 项目管理的体验用接近原生 Rust 的启动和运行速度提供从项目初始化到依赖管理、脚本运行、甚至跨平台发布的完整工作流。本文将带你彻底搞懂uv。我们不止介绍它是什么更会深入剖析它为什么能解决上述痛点它适合谁以及在实际使用中可能遇到的“坑”。你将获得一份从零开始、手把手的实战指南涵盖安装、核心命令、多项目管理、与现有工作流集成以及如何将其融入团队协作和 CI/CD 流程。如果你厌倦了 Python 生态中的工具碎片化和缓慢的依赖解析那么uv很可能就是你一直在寻找的答案。1. 为什么你需要关注 uv它解决了什么根本问题在深入技术细节前我们必须先回答一个核心问题在已有众多工具的 Python 生态中为什么uv值得你投入时间学习uv解决的并非一个“从无到有”的问题而是一个“从有到优”的问题。它的核心价值在于极致的性能与统一简洁的体验具体体现在三个维度1. 依赖解析与安装速度的“降维打击”传统pip在解析复杂依赖关系时可能耗时数分钟甚至更久尤其是在网络不佳或依赖树庞大时。uv利用 Rust 的高性能并发和更优的解析算法将这个过程缩短到秒级甚至毫秒级。这不仅仅是“快一点”而是将原本可能打断心流状态的等待时间彻底消除。2. 一体化工作流告别工具链缝合一个典型的 Python 项目开发流程可能涉及用pyenv或asdf管理 Python 版本用venv创建虚拟环境用pip安装依赖用pip-tools或poetry锁定依赖版本用pytest运行测试用build和twine打包发布。你需要记住不同工具的命令和配置。uv试图用一个二进制文件覆盖所有这些环节uv python install安装 Pythonuv venv创建环境uv pip install安装包uv run运行脚本或命令uv build和uv publish处理分发。这种一致性极大地降低了认知负担。3. 确定性与可复现性提升uv在依赖解析上更加严格和一致。它默认生成uv.lock锁文件类似于poetry.lock或Pipfile.lock确保在任何机器、任何时间安装的依赖版本完全一致。这对于团队协作和持续集成至关重要能有效杜绝“在我机器上能跑”的经典问题。那么uv 最适合谁追求效率的个体开发者无法忍受缓慢的pip install希望工具“快且省心”。需要维护多个项目的工程师快速在不同项目、不同 Python 版本间切换环境。团队技术负责人寻求为团队建立统一、高效、可复现的开发环境规范。CI/CD 流水线维护者需要极速安装依赖以缩短流水线运行时间。如果你属于以上任何一类那么继续阅读uv将很可能成为你的主力工具。2. uv 核心概念与工作原理要高效使用一个工具理解其设计哲学和核心概念是关键。uv虽然命令简单但其背后有几个重要的设计理念。2.1 uv 不是什么是什么uv 不是一个 Python 发行版。它不捆绑 Python 解释器而是帮你下载和管理官方版本的 Python。uv 不只是一个更快的 pip。虽然uv pip命令兼容并大幅加速了pip的工作但uv的野心是整个 Python 项目生命周期。uv 是一个用 Rust 编写的 Python 项目管理工具链。它通过单一二进制提供了 Python 安装、虚拟环境管理、依赖安装与锁定、脚本运行、项目打包等能力。2.2 核心组件解析uv的功能围绕几个核心子命令展开理解它们就理解了uv的全貌uv python: Python 解释器管理。可以从多个源官方构建、conda-forge 等下载、安装、列出和移除特定版本的 Python完全替代pyenv等工具。uv venv: 虚拟环境管理。创建、删除、激活虚拟环境。其创建的环境是标准的venv兼容环境任何能识别venv的工具如 IDE都能正常工作。uv pip: 依赖管理。提供与pip完全兼容的命令行接口但执行速度极快且依赖解析更可靠。它可以直接操作当前激活的虚拟环境也可以通过--python参数指定环境。uv run: 命令执行器。在指定项目的上下文中运行命令。它会自动识别项目根目录通过pyproject.toml等加载对应的虚拟环境然后执行命令。这是实现“一体化”体验的关键。uv sync: 依赖同步。根据pyproject.toml或requirements.txt以及可选的锁文件uv.lock将虚拟环境的依赖同步到指定状态。这是安装依赖的推荐方式因为它保证了确定性。uv lock: 生成锁文件。解析项目依赖并生成一个精确的uv.lock文件记录所有直接和间接依赖的确切版本。uv build/uv publish: 项目打包与发布。构建符合 PyPA 标准的源码分发包和 wheel 包并可发布到 PyPI。2.3 工作流程对比传统 vs. uv为了更直观地理解uv带来的改变我们对比一个常见任务“在新机器上搭建项目环境”的步骤传统流程以 pip venv 为例:检查/安装所需 Python 版本可能用到 pyenv。python -m venv .venv激活虚拟环境.venv\Scripts\activate或source .venv/bin/activate。pip install -r requirements.txt漫长等待。运行项目python main.py。uv 流程:uv python install 3.11如果尚未安装该版本。uv venv --python 3.11 .venv创建环境。uv sync读取pyproject.toml并极速安装所有依赖。运行项目uv run python main.py自动识别.venv并执行。可以看到uv将多个工具的命令统一到了自己的命名空间下并且第 3、4 步的速度和体验有质的提升。更重要的是uv run让你可以不显式激活环境直接运行命令这对于脚本编写和 CI/CD 尤其友好。3. 环境准备与安装 uvuv的安装极其简单它是一个独立的二进制文件无需 Python 环境即可运行。3.1 安装 uv在 Linux/macOS 上使用官方安装脚本是最快的方式。它会下载适合你系统的最新uv二进制文件。# 使用 curl curl -LsSf https://astral.sh/uv/install.sh | sh # 或者使用 wget wget -qO- https://astral.sh/uv/install.sh | sh安装后脚本会提示你将uv所在目录通常是$HOME/.cargo/bin添加到PATH环境变量中。按照提示操作或重启终端即可。在 Windows 上可以使用 PowerShell 安装脚本或者通过包管理器scoop安装。使用 PowerShell:powershell -c irm https://astral.sh/uv/install.ps1 | iex使用 Scoop:scoop install uv验证安装安装完成后在终端中运行以下命令确认安装成功并查看版本。uv --version你应该能看到类似uv 0.4.x (rustc 1.xx.x)的输出。3.2 安装 Python可选但推荐虽然uv可以复用系统已安装的 Python但为了环境隔离强烈建议使用uv python来管理项目专用的 Python 解释器。这能保证项目之间完全独立避免系统 Python 升级带来的影响。使用以下命令查看可安装的 Python 版本并安装一个# 列出所有可安装的 Python 版本 uv python list # 安装特定版本的 Python例如 3.11.9 uv python install 3.11.9 # 安装某个主要版本的最新版例如 3.12 系列的最新版 uv python install 3.12uv会将 Python 安装到其自身管理的目录下如~/.uv/toolchains不会干扰系统 Python。4. 核心工作流实战从零开始一个项目理论说再多不如动手一试。让我们用一个完整的例子演示如何使用uv管理一个 Python 项目的全生命周期。4.1 项目初始化与虚拟环境创建假设我们要创建一个名为my_uv_project的数据分析小项目。# 1. 创建项目目录并进入 mkdir my_uv_project cd my_uv_project # 2. 初始化一个 pyproject.toml 文件如果喜欢手动创建也可以 # 这里我们使用 uv init 来快速生成一个基础模板 uv init --lib # --lib 表示这是一个库项目对于应用可省略或使用 --app执行uv init后会在当前目录生成一个基础的pyproject.toml文件内容大致如下[project] name my_uv_project version 0.1.0 description authors [ {name Your Name, email youexample.com}, ] dependencies [] requires-python 3.8 readme README.md [build-system] requires [hatchling] build-backend hatchling.build接下来我们为这个项目创建一个独立的虚拟环境并指定使用 Python 3.11。# 3. 创建虚拟环境使用我们之前安装的 Python 3.11 uv venv --python 3.11 .venv这会在当前目录下创建一个名为.venv的虚拟环境文件夹。你不需要手动激活它uv的相关命令会自动识别和使用它。4.2 依赖管理安装、锁定与同步现在我们的项目需要pandas和requests库并且为了开发还需要pytest和black。方式一使用uv add(推荐)uv add命令会同时做两件事1) 将依赖添加到pyproject.toml的[project]dependencies或[tool.uv]dev-dependencies部分2) 立即安装它们到当前虚拟环境。# 添加生产依赖 uv add pandas requests # 添加开发依赖测试、格式化等 uv add --dev pytest black执行后你的pyproject.toml会自动更新[project] name my_uv_project version 0.1.0 description authors [ {name Your Name, email youexample.com}, ] dependencies [ pandas2.2,3, requests2.32,3, ] requires-python 3.8 readme README.md [build-system] requires [hatchling] build-backend hatchling.build [tool.uv] dev-dependencies [ pytest8.2,9, black24.4,25, ]同时依赖已经被安装到了.venv环境中。方式二使用uv sync如果你喜欢手动编辑pyproject.toml或者从现有项目只有pyproject.toml或requirements.txt开始可以使用uv sync来安装所有依赖。# 手动编辑 pyproject.toml 添加依赖后运行 uv sync # 如果还有开发依赖一并安装 uv sync --dev生成锁文件为了确保依赖树的确定性我们应该生成锁文件。uv lock这会创建一个uv.lock文件里面记录了pandas、requests、pytest、black以及它们所有间接依赖的精确版本和哈希值。这个文件应该被提交到版本控制系统如 Git中。这样其他协作者或 CI 系统运行uv sync时就能得到完全一致的依赖环境。4.3 运行你的代码与脚本传统方式需要先激活环境source .venv/bin/activate再运行python。uv run让你跳过激活步骤。假设我们有一个简单的脚本src/my_uv_project/analysis.py# 文件路径src/my_uv_project/analysis.py import pandas as pd import requests def fetch_and_analyze(): # 示例获取一些数据 resp requests.get(https://api.github.com/events) events resp.json() # 转换为 DataFrame 并简单分析 df pd.DataFrame(events)[:5] # 取前5条 print(df[[id, type, actor]].to_string()) return df if __name__ __main__: fetch_and_analyze()你可以直接用uv run来执行它# 运行 Python 脚本 uv run python src/my_uv_project/analysis.py # 运行模块 uv run -m my_uv_project.analysis # 运行通过 [project.scripts] 定义的命令行工具如果有 # uv run my-cli-commanduv run会自动发现项目根目录通过pyproject.toml找到关联的虚拟环境.venv并在该环境中执行命令。这意味着你可以在任何子目录下运行它无需关心当前 shell 的环境状态。对于开发任务比如运行测试或格式化代码同样方便# 运行 pytest uv run pytest # 使用 black 格式化代码 uv run black .4.4 项目构建与发布当项目开发完成需要打包分发时uv也能胜任。# 构建源码包和 wheel 包 uv build # 构建完成后会在 dist/ 目录下生成包文件。 # 你可以使用 uv publish 将其发布到 PyPI需要提前配置 token # uv publishuv build会读取pyproject.toml中的[build-system]配置使用指定的后端如hatchling、setuptools进行构建其行为与python -m build完全一致但通常更快。5. 进阶使用场景与技巧掌握了基础工作流后我们来看一些uv在真实开发中能大显身手的进阶场景。5.1 多项目管理与 Python 版本隔离你可能有项目 A 需要 Python 3.9项目 B 需要 Python 3.11项目 C 需要 Python 3.12 的最新特性。用uv管理起来非常清晰。# 为项目 A 创建 Python 3.9 环境 cd /path/to/project_a uv venv --python 3.9 .venv # 为项目 B 创建 Python 3.11 环境 cd /path/to/project_b uv venv --python 3.11 .venv # 为项目 C 安装并创建 Python 3.12 环境 cd /path/to/project_c uv python install 3.12 # 确保有 3.12 uv venv --python 3.12 .venv每个项目的.venv都绑定着特定的 Python 解释器。使用uv run时它会自动选择正确的环境完全无需手动切换。uv python list可以查看所有通过uv安装的 Python 版本。5.2 与现有项目requirements.txt集成很多老项目还在使用requirements.txt。uv对此有很好的支持。# 直接从 requirements.txt 安装极快 uv pip install -r requirements.txt # 将 requirements.txt 转换为 pyproject.toml 并生成锁文件 # 首先确保有 pyproject.toml可以是最简化的然后同步 uv sync --requirements-file requirements.txt # 或者在已有 pyproject.toml 的 [project] 部分添加 # dependencies [package1, package2] 后用 uv sync你也可以让uv同时处理requirements.txt和requirements-dev.txtuv sync --requirements-file requirements.txt --requirements-file requirements-dev.txt --dev5.3 在 CI/CD 中使用 uv在 GitHub Actions、GitLab CI 等环境中uv可以显著缩短流水线时间。以下是一个 GitHub Actions 的示例片段# .github/workflows/test.yml jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: astral-sh/setup-uvv3 # 官方提供的 Action with: python-version: 3.11 - run: uv sync --dev # 极速安装依赖 - run: uv run pytest # 运行测试由于uv sync的速度优势和缓存机制整个安装依赖的步骤可能比传统pip install快 10-100 倍这对于需要频繁运行的 CI 任务来说节省了大量时间和计算资源。5.4 使用 uv 运行任意命令uv run的强大之处在于它可以运行任何命令不仅仅是 Python 脚本。只要该命令存在于虚拟环境的bin或Scripts目录下。# 运行安装在虚拟环境里的 jupyter lab uv run jupyter lab # 运行 ipython uv run ipython # 运行通过 pipx 安装的全局工具如果配置了路径 # uv run --system some-global-tool6. 常见问题与排查思路即使工具设计得再优秀在实际使用中也可能遇到问题。下表总结了使用uv时常见的“坑”及其解决方法。问题现象可能原因排查方式解决方案uv: command not founduv未安装或未正确加入PATH。执行echo $PATH查看路径或尝试~/.cargo/bin/uv --version。1. 重新运行安装脚本。2. 根据安装成功后的提示将export PATH$HOME/.cargo/bin:$PATH添加到~/.bashrc或~/.zshrc并source。uv python install失败或极慢网络问题无法从默认源下载 Python 安装包。检查网络连接观察错误信息是否与下载相关。1. 使用代理或更换网络环境。2. 配置镜像源目前uv对 Python 安装的镜像支持在完善中可关注官方文档。3. 手动下载对应平台的 Python 安装包放入~/.uv/toolchains/cache目录。uv sync或uv add时解析依赖失败依赖声明存在冲突或 PyPI 索引暂时不可用。查看完整错误信息通常uv会给出详细的依赖冲突报告。1. 检查pyproject.toml中dependencies的版本范围是否过于严格或冲突。2. 尝试使用--resolutionlowest或--resolutionhighest来调整解析策略。3. 临时使用--no-cache禁用缓存重试。IDE如 VSCode, PyCharm无法识别uv创建的环境IDE 的 Python 解释器自动发现机制可能未扫描到.venv目录或路径问题。在 IDE 的设置中手动指定 Python 解释器路径。1.VSCode: 按CtrlShiftP输入 “Python: Select Interpreter”选择./.venv/bin/python。2.PyCharm:File - Settings - Project - Python Interpreter点击齿轮图标添加选择./.venv目录。uv run找不到命令1. 虚拟环境中未安装该命令。2. 当前目录不是项目根目录无pyproject.toml。3. 项目根目录下没有.venv。1. 确认命令是否已安装 (uv pip list)。2. 确认当前目录存在pyproject.toml。3. 确认.venv目录存在。1. 使用uv add或uv pip install安装对应包。2. 在项目根目录下执行或使用--project /path/to/project指定项目路径。3. 使用uv venv创建虚拟环境。锁文件uv.lock更新不及时直接使用uv pip install绕过了uv的依赖管理导致锁文件与真实环境不一致。比较uv.lock和uv pip freeze的输出。坚持使用uv add或uv sync来管理依赖避免手动使用uv pip install package。如需更新使用uv add package --upgrade或修改pyproject.toml后运行uv lock。与现有poetry/pipenv项目兼容项目已存在poetry.lock或Pipfile。uv目前主要原生支持pyproject.tomluv.lock或requirements.txt。1.渐进迁移继续用poetry管理依赖但可以用uv run来执行命令享受速度。2.完全迁移将poetry的依赖导出到requirements.txt再用uv sync接管。未来uv可能会增加对Pipfile等的直接支持。7. 最佳实践与工程建议将uv融入个人或团队的工作流遵循一些最佳实践能让收益最大化。将uv.lock纳入版本控制这是保证团队环境一致性的基石。每次依赖变更增、删、升级后都应运行uv lock更新锁文件并提交。CI 系统应使用uv sync --locked来严格安装锁文件中记录的版本。统一项目初始化模板为团队创建一个标准的pyproject.toml模板包含统一的元数据格式、构建后端配置、以及通过[tool.uv]部分预置的常用开发依赖如pytest,black,isort,mypy,ruff。新项目用uv init生成后在此基础上修改。在 CI/CD 中优先使用uv在 GitHub Actions、GitLab CI 等中使用astral-sh/setup-uv等官方 Action 或直接安装uv二进制。用uv sync --dev替代pip install -r requirements.txt和pip install -e .[dev]能大幅缩短流水线运行时间。利用uv run简化脚本和文档在项目的README.md或Makefile中使用uv run作为命令前缀。例如将“运行测试”的指令从复杂的“激活环境后运行 pytest”简化为uv run pytest。这降低了新成员的参与门槛。谨慎处理全局安装uv管理的 Python 和虚拟环境默认是项目本地的。避免使用uv pip install --system进行全局安装以免污染系统环境。如果需要全局工具考虑使用pipx。监控依赖更新定期使用uv pip list --outdated检查过时的依赖。升级时使用uv add package --upgrade来更新pyproject.toml并重新生成锁文件而不是直接uv pip install --upgrade。理解uv的边界uv目前主要聚焦于“项目管理”和“包管理”。对于更复杂的多环境管理如需要同时管理 Node.js、Go 等asdf仍是更好的选择。对于需要复杂发布流程或私有仓库特殊配置的项目可能仍需结合twine、flit等工具。uv的出现标志着 Python 工具链在追求“开发者体验”和“极致性能”上迈出了关键一步。它没有引入革命性的新概念而是通过 Rust 重写和精心的设计将现有最佳实践整合并加速到了一个全新的水平。对于个人开发者它是提升日常效率的利器对于团队它是建立标准化、高效能工程规范的强大助推器。开始尝试uv的成本很低只需安装一个二进制文件。不妨从下一个个人小项目开始或者在一个现有项目中试用uv run来运行测试和脚本亲身感受其速度与便捷。随着你对它的熟悉很可能会发现你已经回不去那个需要频繁激活环境、等待漫长pip install的时代了。
