你是不是也被 Python 的包管理折腾过pip install慢、虚拟环境建了又建、Python 版本切换全靠手动改环境变量。这几年冒出来的uv一句“用 Rust 写的极速 Python 包管理器”就让很多人开始关注。这周我在 Windows 上完整走了一遍安装和基础使用流程踩了几个坑也验证了不少网上说法写出来给你做参考。这篇不讲虚的直接说清楚 uv 是什么、Windows 上怎么装、以及那些真正高频的基础用法。先说结论如果你的日常工作离不开 Python尤其是同时维护多个项目、频繁要切换依赖环境uv值得从今天开始用起来。它把 Python 解释器管理、虚拟环境创建、依赖安装与锁定这三件事合并成一个工具而且速度确实快不是营销话术。1. uv 到底是个什么工具1.1 它解决的三个痛点在 uv 出现之前一个典型的 Python 项目初始化流程是这样的先安装 Python 解释器然后创建虚拟环境python -m venv venv激活环境Windows 上还要敲.\\venv\\Scripts\\activate再用pip install逐个或者按 requirements.txt 装依赖。如果同时管理 Python 3.9 和 3.12 两个项目你还得额外装 pyenv-win或者在系统环境变量里反复切换。uv 把这些步骤合并成了一个命令流。它由 Astral 公司开发底层用 Rust 实现核心能力包括Python 版本管理直接uv python install 3.12下载解释器并管理版本不需要 pyenv。虚拟环境管理uv venv一行创建环境并且自动在项目目录下生成.venv。依赖安装与锁定uv add requests安装依赖并写入 pyproject.toml同时生成 uv.lock 锁定精确版本类似 Node.js 的 package-lock.json。简单类比uv 之于 Python就像 npm 之于 JavaScript——一个工具串起依赖、环境和脚本执行但速度和体感上又比 npm 更轻。1.2 为什么速度能这么快网上宣传“比 pip 快 10 倍”这不是夸张核心在于三点一是用 Rust 重写了下载、解析和构建过程底层并发能力远强于 Python 写的 pip二是全局缓存机制同一个包只要下载过一次后续项目秒装不再重复拉取三是依赖解析基于锁文件增量进行不会每次全量扫描 PyPI。实际体验中冷缓存环境下uv pip install pandas相比pip install pandas的差距大概在 3 到 5 倍热缓存下几乎是瞬间完成。对于需要频繁重建 CI 环境或者本地切换分支的人来说这个加速度体感很明显。2. 在 Windows 上安装 uv 的完整流程2.1 官方推荐的 PowerShell 安装方式Windows 10 及以上系统推荐直接用 PowerShell 执行安装命令这是 uv 官方文档的首选方式。打开 PowerShell输入powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex这条命令做的事情很简单从 uv 官网拉取安装脚本然后立即执行。脚本会把 uv 的可执行文件下载到%USERPROFILE%\\.local\\bin目录下并在用户环境变量 PATH 中追加这个路径。安装完成后必须重开一个全新的 PowerShell 窗口否则系统不会加载新的环境变量。然后验证uv --version如果输出类似uv 0.8.x (a8a0c1e 2025-xx-xx)这样的版本信息说明环境变量生效了。注意如果你是在 Windows Terminal 里安装的装完建议直接关掉整个 Terminal 标签页再重开。只清屏或开新标签有可能读不到新 PATH这是 Windows 环境变量刷新的老问题。2.2 遇到执行策略限制怎么办很多 Windows 机器默认 PowerShell 执行策略是 Restricted运行上面的命令会直接报错提示“此系统上禁止运行脚本”。解决办法有两种。第一种临时放开策略推荐用完改回来Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process这个命令只对当前 PowerShell 会话生效不会改动系统设置。执行后再跑官方安装命令即可。第二种如果公司电脑有组策略锁死不允许改执行策略那就走手动安装路线去 uv 官方 GitHub Releasesastral-sh/uv下载 Windows 版本的 zip 包一般是uv-x86_64-pc-windows-msvc.zip。解压后把文件夹放到一个固定位置比如D:\\Tools\\uv然后把D:\\Tools\\uv手动加到系统环境变量 PATH 里。这种方式也不复杂适合需要离线安装的环境。2.3 PowerShell 长时间卡住或下载中断有时候执行安装命令会卡在 “Downloading” 半天不动大概率是网络到 astral.sh 不通畅。国内用户最省事的办法是先配置镜像环境变量再执行安装。和 pip 一样uv 支持通过环境变量指向国内镜像源。安装 Python 解释器时设置:$env:UV_INDEX_URL https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple $env:UV_INSTALLER_PYTHON_BASE_URL https://mirrors.tuna.tsinghua.edu.cn/python第一条让 uv 从清华镜像下载 PyPI 包第二条让 uv 安装 Python 解释器时走清华的 Python 发行版镜像。如果你用的是华为云或其他镜像把域名替换成对应的地址即可。如果安装脚本本身无法下载也还有一个更省心的思路直接先安装一个 Python 3.10再用 pip 安装 uvpip install uv这种方式装的 uv 也完全可用之后 uv 依然可以通过uv python install管理更多 Python 版本。相比官方脚本pip 方式会受限于当前 Python 环境的包依赖核心功能完全一致。2.4 验证安装是否成功的三个标准我建议装完之后做三件事确认环境没有隐患uv --version有正常输出。执行uv python list能看到当前 uv 已经识别到的系统 Python 版本列表。初次运行时它还会扫描系统里已有的 Python。在一个临时目录里执行uv venv test-env能自动创建虚拟环境且当前用户目录下生成AppData\\Local\\uv缓存目录。缓存目录出现了说明 uv 开始正常工作。这个目录之后还会成为磁盘空间大户后面我会专门讲怎么迁移它。3. uv 基础用法这些是真正的日常高频操作3.1 初始化一个项目假设你想新建一个数据处理项目传统做法是手动建目录、建 venv、写 requirements.txt。uv 的做法uv init my-data-project cd my-data-project uv add pandas numpy执行完目录下会出现这些文件pyproject.toml # 项目依赖声明文件 uv.lock # 锁定文件记录精确版本 src/main.py # 入口文件 .gitignore # 含 .venv 的忽略规则神奇的地方是uv add会自动创建.venv虚拟环境不需要你手动执行python -m venv。第一次 add 会自动下载并安装 pandas 和 numpy并在 pyproject.toml 中写入[project] dependencies [ numpy2.0, pandas2.2, ]后续任何人拿到这个项目只需要一条uv sync就自动建环境并按锁文件装依赖版本完全一致。3.2 日常开发三件套run / sync / add如果你已经有项目或者在 GitHub 克隆了别人用 uv 管理的项目高频命令就这三个uv sync # 按 pyproject.toml uv.lock 安装/更新所有依赖 uv add requests # 新增一个依赖包其他包不会被重复解析 uv run python main.py # 在项目虚拟环境中运行脚本无需手动激活环境重点说说uv run。传统流程是先激活环境再执行脚本在 Windows 下激活环境还要注意命令是.\\venv\\Scripts\\activate偶尔忘激活直接用系统的 Python 跑版本不对直接蒙圈。uv run解决了这个问题——它自动检测当前目录的.venv有就用没有就报错并提示先uv sync。这让“打开终端就干活”成为可能不用时刻惦记着环境状态。3.3 安装特定版本的 Python 解释器Windows 上最常碰到的问题是我想在 Python 3.8、3.11、3.12 之间切换项目开发系统里只装了一个版本怎么办。uv 的做法uv python install 3.8 3.11 3.12 uv python pin 3.12 # 在项目目录中锁定用 3.12第一条命令会把三个 Python 版本都下载到 uv 的全局管理目录里在 Windows 上位于%USERPROFILE%\AppData\Local\uv\python。第二条命令会在当前项目的pyproject.toml里写入requires-python 3.12后续uv sync时自动选择 3.12。这样版本管理彻底从“改系统环境变量”转向“项目内声明”。你可以同时开着三个不同 Python 版本的项目互相不干扰。提醒下载 Python 解释器的过程也走网络。如果你等了很久还没装好默认走官网源。想加速就设置UV_INSTALLER_PYTHON_BASE_URL指向国内镜像。3.4 切换环境与清理项目多了以后你会需要快速查看当前有哪些虚拟环境、怎么干净地重置一个环境。几个实用命令uv venv --clear # 清空当前 .venv 里的所有包然后重建 uv cache clean # 清空全局缓存相当于 npm cache clean uv cache dir # 看一下缓存目录在哪执行uv venv --clear之后下一次uv sync会重新拉取所有依赖但因为有全局缓存如果包没更新过基本秒级重建。如果你要从“一种项目依赖状态”切换到“另一种”不需要手工删虚拟环境直接改 pyproject.toml 后uv sync即可。uv 会根据锁定文件差异只增删变化的部分比整体重建快很多。3.5 PyCharm 怎么使用 uv很多读者在热搜里提到了 PyCharm 和 uv 的配合。现在 PyCharm 2024.3 版本已经原生支持 uv创建新项目时 “New environment” 里可以选 “Custom environment”指向 uv 创建的.venv即可。最直接的做法是项目目录下先uv sync然后在 PyCharm 的 Settings - Project - Python Interpreter 里点击Add Interpreter选择Existing路径指向当前项目下的.venv\\Scripts\\python.exe。PyCharm 会把这个解释器与项目绑定终端、调试器、代码补全都用这个环境不需要额外配置。如果你用的是 VS Code更简单默认选择解释器时它会自动识别.venv。4. 常见问题与排查技巧实录4.1 uv 默认把缓存放在 C 盘越用越大uv 会把所有下载过的包、Python 解释器都缓存到C:\\Users\\你的用户名\\AppData\\Local\\uv目录下。用一段时间后这个目录可能轻松超过 10GBC 盘小的会顶不住。解决方案是迁移缓存目录# 新建一个目录 mkdir D:\\uv-cache # 设置环境变量 [Environment]::SetEnvironmentVariable(UV_CACHE_DIR, D:\\uv-cache, User)设置完重开终端uv 会把新缓存写到 D 盘。原来 C 盘里的内容可以手动删除也可以先复制过去保留旧缓存实现无缝迁移。我建议直接删除让 uv 重新热缓存——常用的包本来不多缓存重建很快省下的空间更值钱。4.2 报错 “Failed to download” 或安装 Python 失败排查思路按顺序来网络层是否稳定换镜像源环境变量再看。更新 uv 版本uv self update有些早期版本对 Windows 的路径兼容不够好。关闭安全软件、防火墙的拦截提示重新执行安装。查看详细报错uv sync --verbose。我在使用早期版本时遇到过 Windows Defender 把 uv 的 Python 下载缓存当风险文件处理导致安装一半失败。加入白名单或者升级版本后解决。4.3 电脑上已有多个 Python 版本uv 选错了启动uv run时如果项目里的 pyproject.toml 没写requires-pythonuv 会优先使用调和分析器识别出的最新版本。但你也许就是想在 3.8 上跑老项目。这时候不要靠系统环境变量去“抢”正确做法是uv python pin 3.8 uv sync这会明确指定项目所需的 Python 版本比在系统里卸载其他版本安全得多。4.4 uv.lock 和 requirements.txt 该怎么取舍如果你的项目需要交接给不用 uv 的同事或者有老旧的 Dockerfile 仍然用 pip 安装依赖还是需要生成 requirements.txtuv export --format requirements-txt -o requirements.txt这会把锁文件里的精确版本导成 pip 可读格式。但日常开发中我建议让 uv.lock 成为唯一事实来源不要手写维护 requirements.txt。uv.lock 除了锁定版本还包含 hash 校验和交付更安全。4.5 如何干净地卸载 uv用官方脚本安装的 uv卸载分两步删除可执行文件所在目录%USERPROFILE%\\.local\\bin里的 uv 相关文件uv.exe、uvx.exe然后清理AppData\\Local\\uv缓存目录。如果是 pip 装的 uv直接pip uninstall uv顺带把 PATH 环境变量里.local\\bin的条目删掉。脚本会创建这个路径留着不影响但干净起见建议一并移除。5. 一些更进阶但很实用的配置思路5.1 国内 pip 源配置一次到位刚接触 uv 的读者很容易在第一次uv add时遇到下载慢的问题。建议在用户环境变量中一次性配好[Environment]::SetEnvironmentVariable(UV_INDEX_URL, https://pypi.tuna.tsinghua.edu.cn/simple, User)这样后续所有uv add和uv sync默认走清华镜像不用每次敲参数。设置后重开终端生效输入uv cache dir不影响命令行为层面会被持久读取。5.2 使用 uv 管理命令行工具除了项目依赖uv 还可以全局安装命令行工具比如 ruff、mypy、jupyterlabuv tool install ruff uv tool install mypy uvx pyright --versionuv tool相当于 pipx 的替代品工具会安装在隔离环境里但可执行文件链接到系统 PATH。这样可以避免全局环境被各种工具依赖搞乱。用一段时间的 jupyter、ruff、mypy 都在全局隔离环境中系统 Python 保持干净。5.3 在 CI 或 Docker 里的用法参考虽然这篇重点在 Windows但如果你后续会在 Linux 构建环境或 Docker 容器里用 uv思路相同先安装 uv然后uv sync --frozen完全按 uv.lock不更新锁文件装依赖跑测试。--frozen参数推荐所有 CI 场景都用保证构建可复现。个人使用体会从 pip venv pyenv-win 的组合切到 uv花了两三天度过“肌肉记忆期”之后就回不去了。最让我舒服的是uv run和uv sync的设计环境问题被工具内化了不需要再手动思考和执行一系列命令。如果你正在管理多个 Python 项目并且受够了环境切换带来的心智负担我建议你本月内留出一个小时把手里最不重要的项目先迁移到 uv 上走通整个流程你会回来感谢自己做出的这个小改变。