最近把用了好几年的pip pipenv工具链整个换成了uv说实话这个决定比我想象中果断得多。uv是 Astral 公司开源的新一代 Python 包管理工具底层用 Rust 编写官方定位就是一套组合拳替代pip、pip-tools、virtualenv、pyenv这些分散的工具。我用下来的直接感受是虚拟环境创建、包安装、Python 版本管理原来三四个命令做的事现在一个uv全搞定速度还快到离谱。这篇文章就围绕uv的安装与使用把我从零上手到现在稳定使用的完整经验整理出来。无论你是在 Windows 11 上刚接触uv的新手还是已经在别的项目里见过uv但一直没空深入研究的老 Python 开发者这篇应该都能给你一点参考。内容会覆盖环境搭建、镜像配置、项目初始化、Python 版本切换、uv tool安装全局命令行工具以及我在实际使用中踩过的坑。1. 为什么我推荐把工具链换成 uv1.1 uv 到底帮你干掉了什么先别急着装搞清楚uv定位是什么后面用起来才会顺手。传统 Python 开发环境里我们通常需要这样一套组合pip安装第三方包virtualenv/venv创建隔离的虚拟环境pyenv管理多个 Python 版本pip-tools锁定依赖版本、生成 requirements 文件可能再来一个poetry或者pipenv管理项目依赖这套方案不是不好但问题在于工具之间是割裂的。pip只管装包venv只管隔离pyenv只管 Python 版本出了问题你得分别排查。而且pip的解析依赖速度在项目变大之后会明显变慢装一个稍微重量级的包经常要转几十秒。uv做的事情就是把这几个工具的职责全部合并到一起。它内部自带依赖解析器、虚拟环境管理、Python 解释器下载和全局缓存机制。用uv创建一个项目环境相当于同时完成了virtualenv创建环境、pip install安装依赖、pip freeze生成锁文件这几件事。我把它在项目中的角色总结成一张对照表传统工具对应 uv 命令作用pip installuv pip install/uv add安装包pip uninstalluv pip uninstall/uv remove卸载包pip freezeuv pip freeze导出已安装包列表virtualenvuv venv创建虚拟环境pyenv installuv python install安装指定 Python 版本pip-toolsuv lock/uv sync锁定依赖并同步环境1.2 uv 相比 poetry / pipenv 的优势很多朋友问既然有poetry这么成熟的工具为什么还要换uv我在多个项目里对比过主要优势是三点首先是速度。uv的依赖解析性能比pip高一个数量级尤其当你面对的是几十上百个间接依赖的大型项目时体感非常明显。我经常需要给项目从零搭建环境uv sync创建虚拟环境加装全部依赖通常在几秒内完成而poetry install那套流程往往要等咖啡。其次是架构简化。poetry把依赖管理做进pyproject.toml但同时保留着自己的锁文件格式和安装后端当你需要和 CI 流程、Docker 镜像构建配合时中间多出来的概念和配置项都是认知负担。uv的思路更贴近“一个命令就位”的哲学它对 PEP 621 标准支持得非常干净pyproject.toml里的依赖声明直接可用不必额外理解一套 poetry 专属语法。然后是Python 版本管理。uv内置了 Python 解释器下载功能不需要单独装pyenv在 Windows 上尤其方便——不用去官网手动下安装包一条uv python install 3.12就搞定版本切换也直接在项目目录下完成。2. Windows 11 下安装 uv 的几种方式与镜像配置2.1 安装命令与安装后的文件位置uv的安装方式在不同平台有一些差异这里主要讲 Windows 11 环境。最简单的方式是打开 PowerShell执行官方安装脚本powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex国内网络环境下如果astral.sh访问不稳定可以考虑从 GitHub Releases 手动下载或者用包管理器安装winget install --idastral-sh.uv安装完成后uv默认会被放在C:\Users\你的用户名\AppData\Local\uv目录下。这个路径也是你卸载时需要关注的地方目录里除了uv.exe还有uninstall.exe如果哪天想彻底移除直接运行卸载程序即可。很多刚装完的朋友会遇到一个“命令未找到”的问题。原因很简单安装脚本执行完后新加入的环境变量PATH并不会在已经打开的终端里自动生效。你需要重新开一个 PowerShell 窗口或者在当前窗口手动执行$env:Path $env:USERPROFILE\AppData\Local\uv;$env:Path验证安装是否成功直接看版本号uv --version如果输出版本信息说明安装没问题。2.2 国内环境下必须先配置镜像源安装完uv后第一步不是急着创建项目而是配置镜像源。uv默认从 PyPI 官方源下载包国内网络环境下速度很不稳定尤其装一些体积大的包时超时重试的体验非常糟糕。推荐把默认索引切换到清华镜像或阿里云镜像。uv支持在配置文件里设置。全局配置文件在用户目录下的%APPDATA%\uv\uv.tomlWindows没有的话手动创建即可[[index]] url https://mirrors.tuna.tsinghua.edu.cn/pypi/simple default true不想写配置文件的话用环境变量UV_INDEX_URL也可以直接生效[System.Environment]::SetEnvironmentVariable(UV_INDEX_URL, https://mirrors.tuna.tsinghua.edu.cn/pypi/simple, User)这里有个细节UV_INDEX_URL是全局环境变量优先级高于配置文件内index-url的设置。如果你有特殊需求只想在当前项目里用某一个私有源可以在项目pyproject.toml里的[tool.uv]段落添加配置这是后话。2.3 升级与卸载uv更新频率很高新版本经常有功能改进和 bug 修复。升级命令很简单uv self update如果你用的是pip装的uv开发版那就走pip install -U uv但推荐还是用官方脚本方式安装这样uv self update能直接生效。卸载就用最开始安装目录里的uninstall.exe或者如果你不想保留缓存目录连C:\Users\你的用户名\AppData\Local\uv整个删掉也行这个目录里主要是程序本体和部分配置。3. 用 uv 管理项目依赖与切换 Python 环境3.1 从一个空目录开始初始化项目假设现在要开一个全新的 Python 项目用uv的流程非常简洁。找一个空目录执行uv init my-demo cd my-demouv init会帮你生成一个pyproject.toml文件、一个基本的README.md还有.gitignore。打开pyproject.toml你会看到类似这样的结构[project] name my-demo version 0.1.0 description Add your description here readme README.md requires-python 3.12 dependencies []注意这里没有[build-system]因为uv不要求项目必须以可安装包的形式存在它可以纯粹作为依赖管理文件来使用。接下来安装依赖uv add requests httpx这条命令会做三件事把requests和httpx写入pyproject.toml的dependencies列表生成一个uv.lock锁文件在当前项目目录下创建.venv虚拟环境并同步安装这两个包。如果项目里已经有别人提交的pyproject.toml和uv.lock你只需要一条命令就能把环境完整还原uv sync这条命令会读取锁文件创建虚拟环境并精确安装锁文件里指定的版本。你不需要先activate环境日常跑脚本直接用uv run python main.pyuv run会自动使用当前项目的.venv环境比手动activate再python main.py省一步。这也解决了我以前的一个痛点每次开新终端都要先想一下这个项目该激活哪个环境。3.2 切换 Python 版本很实用的日常操作uv最有价值的场景之一就是 Python 版本管理。我们经常面临不同项目需要不同 Python 版本的情况以前在 Windows 上我只能去官网手动下载解释器装完还要自己配置系统环境变量。现在uv把这件事变成了两条命令。首先查看当前有哪些 Python 版本可用uv python list安装一个指定版本uv python install 3.12安装完成之后在项目目录里把版本固定住uv python pin 3.12此时uv会在pyproject.toml旁边生成一个.python-version文件内容就是3.12。以后在这个目录下执行任何uv run或uv sync都会自动使用 3.12 版本。如果你本地没有装过 3.12uv会在第一次运行时提示你也可以直接让uv run自动完成下载这个体验做到了真正意义上的开箱即用。注意一个容易混淆的点uv python pin只是指定了项目要用的 Python 版本并不会破坏系统里其他项目对别的版本的依赖。每个项目的.python-version是独立的由项目目录决定这比传统方式安全很多。3.3 日常依赖管理命令速查用uv一段时间后我常用的命令基本稳定在这几个操作命令说明添加依赖uv add numpy安装并写入 pyproject 和 lock 文件移除依赖uv remove numpy卸载并更新 lock 文件同步环境uv sync按 lock 文件还原环境更新全部依赖uv lock --upgrade重新解析依赖并升级到新版本查看已安装uv pip list列出当前虚拟环境安装的包导出 requirements 文件uv export --format requirements-txt requirements.txt生成兼容 pip 的 requirements 文件日常添加依赖时我建议优先使用uv add而不是uv pip install两者区别是uv add会把依赖写入项目配置和锁文件做到可重复还原uv pip install只是临时安装不会改动pyproject.toml如果你只是想在环境里临时装个工具试验一下用它更合适。4. uv tool管理全局命令行工具的另一种姿势4.1 为什么需要 uv tool除了项目依赖我们平时还会用 Python 安装一些全局命令行工具比如代码格式化工具ruff、HTTP 客户端httpie、或者数据库迁移工具。以前的做法是pip install --user ruff装完之后全局环境里的包越来越多时间一长根本记不清哪个工具属于哪个项目。uv tool就是为解决这个问题设计的。它把每个命令行工具安装进一个独立的隔离环境然后通过入口脚本暴露命令。好处是显而易见的每个工具环境相互独立、互不干扰卸载时不会误删全局包也不会因为某个工具升级把其他工具的依赖弄坏。4.2 实际安装一个工具试试官方文档里给过一个例子运行这样的命令可以安装specify-cliuv tool install specify-cli再举一个更常见的例子uv tool install ruff安装完成后ruff命令直接可用。查看已经装了哪些工具uv tool list输出会列出工具名、安装路径、暴露的命令入口。升级某个工具也很直接uv tool upgrade ruff想卸载某个工具uv tool uninstall ruff如果你不想把工具持久安装只是临时用一下uvx是你的好帮手。比如临时检查代码风格uvx ruff check .uvx会先检查缓存里有没有该工具有的话直接运行没有就先创建隔离环境安装再运行用完不影响系统环境。这个机制和npx在 Node 生态里的角色非常像我建议所有临时性操作都用uvx持久化工具才用uv tool install。4.3 uv tool 与项目依赖的边界需要强调一个使用边界uv tool install装的工具是项目无关的它们不和任何具体项目绑定。如果你正在某个uv管理的项目里想给这个项目加一个开发依赖比如pytest不要用uv tool install应该用uv add pytest --dev这样 pytest 才会进入项目锁文件并被其他协作者同步。uv tool解决的是“全局环境里的命令行工具”uv add解决的是“项目里的依赖包”两者职责不同混用会导致环境混乱。5. 常见问题与排查心得5.1 高频问题速查表用uv这段时间我遇到过不少问题有些是文档里没直接写清楚的这里整理成一张速查表问题原因解决办法输入uv提示找不到命令PATH 未生效重开终端或手动添加%USERPROFILE%\AppData\Local\uv到 PATH下载第三方包超时默认 PyPI 源速度慢配置清华/阿里云镜像源或设置UV_INDEX_URL环境变量uv run提示找不到 Python 版本本地未安装对应版本执行uv python install 版本号自动补充安装包后项目里 import 不到没有用uv add临时安装进了全局环境检查uv pip list和uv pip freeze确认环境缓存占用空间较大uv 全局缓存默认保留所有下载过的包用uv cache dir查看路径uv cache clean定期清理和 pip 混用时环境不一致pip 和 uv 各自维护不同的依赖元数据项目统一用uv add/uv sync避免手动pip install进同一环境5.2 我踩过的几个坑第一个坑是项目里混用 pip 和 uv。有一次我通过uv add安装了pydantic和fastapi后来觉得版本不对习惯性进入.venv用pip uninstall卸载了其中一个。结果下次再执行uv sync时uv发现锁文件里要求的依赖和当前环境不一致自动重新把包安装了回来我当时的疑惑是“为什么我刚卸载的包又回来了”后来才明白uv sync会把环境收敛到与锁文件完全一致的状态。所以记住在 uv 管理的项目里安装和卸载依赖都走 uv 命令别手痒去用 pip。第二个坑是缓存目录占用磁盘空间。uv 的缓存机制非常激进下载过的所有包、构建过的版本都会保留在本地缓存里好处是再次创建环境时极快坏处是缓存目录会悄悄变大。Windows 上缓存默认在C:\Users\用户名\AppData\Local\uv\cache我有一阵子没管它结果占了 6 个多 G。平时不用刻意清理但如果磁盘吃紧uv cache clean不会有副作用顶多下次创建环境时重新下载。第三个坑和 Windows 终端有关。PowerShell 默认执行策略可能禁止运行脚本如果安装脚本提示权限问题在短期的 PowerShell 窗口里用Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass临时绕过即可。另外如果你在路径里包含中文字符的项目目录下使用 uv部分旧版本可能存在问题升级到新版基本都能解决。一点使用心得最后分享一个我自己的切身体会uv最大的优点不是某个单一功能而是它把所有 Python 环境管理动作统一到了一个心智模型里。以前我需要记住东西太多了——pip install、venv activate、pyenv local、pip freeze还要手动维护 requirements 文件。现在对我来说一个新项目从零到可运行只需要三个命令uv init、uv add、uv run而且每个命令都很快。如果你现在还在使用pip virtualenv的老一套我建议挑一个不那么紧急的小项目试着用uv重新搭建一遍环境跑通之后大概率就不想回去了。uv sync配合锁文件的还原方式也让团队协作变得轻松了很多新同事克隆代码后一条命令就能把环境拉到和 CI 一致的状态再也不用对着 README 里五花八门的安装步骤猜来猜去。