uv 安装与使用教程：Windows 与 Linux（含 WSL）完整上手指南

本文适合 Python 开发者、服务器部署人员、准备从 pip / virtualenv / pipx / poetry 迁移到 uv 的用户。WSL 本质上运行的是 Linux 用户态环境，所以本文把 WSL 归到 Linux 部分一起讲。

uv 是 Astral 推出的 Python 包管理与项目管理工具，使用 Rust 编写。官方给它的定位很直接：一个极快的 Python package and project manager。它可以同时覆盖包安装、虚拟环境、项目依赖、锁文件、Python 版本管理、脚本依赖声明、命令行工具安装等场景。

如果你以前经常在这些工具之间来回切换：

  • pip：安装 Python 包；
  • venv / virtualenv：创建虚拟环境；
  • pip-tools：生成和同步 requirements 锁定文件；
  • pipx：安装 Python 命令行工具；
  • poetry / rye：做项目依赖管理；
  • pyenv：管理 Python 版本；

那么 uv 的价值就在于：尽量用一个命令体系把这些事情统一起来。

uv 官方基准图：安装 Trio 依赖
uv 官方文档/README 中的基准图：在 warm cache 场景下安装 Trio 依赖。图片来源：Astral uv 官方仓库。

1. uv 适合解决什么问题？

简单理解，uv 可以分成 5 个常用场景。

场景 常用命令 作用
管理 Python 版本 uv python install、uv python list、uv python pin 安装、查看、固定项目 Python 版本
管理项目 uv init、uv add、uv remove、uv sync、uv lock、uv run 创建项目、添加依赖、同步环境、运行命令
运行脚本 uv run、uv add --script、uv init --script 给单文件脚本声明依赖并隔离运行
安装命令行工具 uvx、uv tool install、uv tool upgrade 类似 pipx，运行或安装 Python CLI 工具
兼容 pip 工作流 uv venv、uv pip install、uv pip sync、uv pip freeze 在旧项目中替代 pip / virtualenv 的一部分用法

日常开发中，我建议把 uv 当成两层来用：

  1. 新项目优先用 uv 的项目模式：uv init、uv add、uv sync、uv run。
  2. 老项目或临时环境用 pip 兼容模式：uv venv、uv pip install、uv pip sync。

这样不容易混乱。

2. Windows 安装 uv

Windows 下推荐优先使用官方 PowerShell 安装脚本。打开 PowerShell，执行：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，重新打开 PowerShell，检查：

uv --version

或者直接输入：

uv

正常情况下会看到 uv 的帮助菜单。

2.1 Windows 下的其他安装方式

如果你更喜欢包管理器，也可以用下面几种方式。

WinGet

winget install --id=astral-sh.uv -e

Scoop

scoop install main/uv

pipx

如果你已经安装了 Python 和 pipx：

pipx install uv

pip

也可以直接用 pip：

pip install uv

不过如果是长期使用，我更推荐官方安装脚本、WinGet、Scoop 或 pipx，不太建议把 uv 直接塞进某个业务项目的 Python 环境里。

2.2 Windows 安装后找不到 uv 怎么办？

如果安装后提示：

uv : 无法将“uv”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

通常是 PATH 还没有刷新。可以按顺序排查：

  1. 关闭当前 PowerShell，重新打开；
  2. 检查 $HOME\.local\bin 是否存在；
  3. 检查 uv.exe 是否在 $HOME\.local\bin 目录里；
  4. 如果不在 PATH，把 $HOME\.local\bin 加入用户环境变量 Path。

PowerShell 中可以临时测试：

$env:Path = "$HOME\.local\bin;$env:Path"
uv --version

这个命令只对当前窗口生效，永久生效还是建议通过 Windows 的“环境变量”界面添加。

2.3 Windows 开启命令补全

PowerShell 下可以执行：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

如果你经常用 uvx，也可以补上：

Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

然后重启 PowerShell。

3. Linux / WSL 安装 uv

Linux 和 WSL 使用同一套命令。官方推荐使用安装脚本：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果系统没有 curl，可以用 wget：

wget -qO- https://astral.sh/uv/install.sh | sh

安装后重新打开终端，或者按安装脚本提示刷新 PATH，然后验证：

uv --version

3.1 WSL 用户需要注意什么？

WSL 里执行 Linux 命令即可，不要在 WSL 里使用 Windows 的 PowerShell 安装脚本。

推荐做法：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

WSL 中的 uv 会安装在 Linux 用户目录下，和 Windows 里的 uv 不是同一个文件。也就是说：

  • Windows PowerShell 里的 uv.exe 是 Windows 版本；
  • WSL Ubuntu 里的 uv 是 Linux 版本；
  • 两边的 Python、虚拟环境、缓存目录通常也是分开的。

这其实是好事，能减少 Windows 和 Linux 路径混用导致的问题。

3.2 Linux 下的其他安装方式

pipx

pipx install uv

pip

pip install uv

Homebrew on Linux

如果服务器或开发机上已经有 Homebrew：

brew install uv

Cargo

如果你本来就是 Rust 用户，也可以：

cargo install --locked uv

不过 Cargo 会从源码构建，普通用户没必要优先选择这种方式。

3.3 Linux 开启命令补全

Bash：

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
source ~/.bashrc

Zsh：

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc

fish：

echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
echo 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish

4. 更新和卸载 uv

如果你是通过官方 standalone installer 安装的 uv，可以直接自更新：

uv self update

Windows PowerShell 里同样是：

uv self update

如果你是通过 pip 安装的，使用 pip 更新：

pip install --upgrade uv

如果你通过 WinGet、Scoop、Homebrew 安装，就用对应包管理器升级。

卸载前可以先清理 uv 缓存和 uv 管理的数据：

uv cache clean

Linux / WSL 删除二进制：

rm ~/.local/bin/uv ~/.local/bin/uvx

Windows PowerShell 删除二进制：

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

5. 第一个 uv 项目

新建一个项目：

uv init hello-uv
cd hello-uv

uv 会生成一个基础项目结构，一般包括：

hello-uv/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

运行项目：

uv run main.py

第一次运行时，uv 会按需要创建 .venv 虚拟环境，并根据项目配置准备依赖。

添加依赖：

uv add requests

再打开 pyproject.toml，会看到 requests 已经进入项目依赖。uv 还会更新 uv.lock，用于锁定具体解析出来的依赖版本。

删除依赖：

uv remove requests

查看依赖树：

uv tree

同步环境：

uv sync

运行任意命令：

uv run python --version
uv run python main.py
uv run pytest

在 uv 项目里，uv run 的意义很重要：它会确保命令运行在项目环境中，并按锁文件同步依赖。很多时候你不需要手动激活 .venv。

uv 官方基准图
uv 官方仓库中的另一张基准图。图片来源：Astral uv 官方仓库。

6. Windows 和 Linux 的虚拟环境激活差异

虽然 uv 项目推荐直接使用 uv run，但有时你还是想手动进入虚拟环境。

先创建虚拟环境：

uv venv

Windows PowerShell 激活：

.venv\Scripts\activate

Linux / WSL 激活：

source .venv/bin/activate

退出虚拟环境：

deactivate

这里有个容易混淆的点：

  • uv run python main.py：不需要手动激活虚拟环境；
  • python main.py：如果不用 uv run，就需要确认当前 shell 已经激活了正确的 .venv。

个人建议：项目内优先写 uv run，少依赖手动激活状态。这样命令更可复制，也更适合 CI/CD。

7. 管理 Python 版本

uv 不仅能管理依赖，也能管理 Python 解释器。

安装最新 Python：

uv python install

安装指定版本：

uv python install 3.12

一次安装多个版本：

uv python install 3.11 3.12

查看可用版本：

uv python list

让当前项目固定使用 Python 3.12：

uv python pin 3.12

这会写入或更新 .python-version。之后 uv 在创建项目环境时，会优先使用这个版本。

临时用某个 Python 版本运行命令：

uv run --python 3.12 python --version

如果本机没有对应版本，uv 可以按需自动下载。对服务器来说，这一点很方便：你不需要为了一个项目手动折腾系统级 Python。

8. 使用 uv 运行单文件脚本

有些脚本不值得建完整项目，比如一个爬虫、一个数据清洗脚本、一个临时运维脚本。以前常见做法是先建 venv，再 pip install。uv 可以把依赖声明写进脚本本身。

创建脚本：

uv init --script demo.py --python 3.12

给脚本添加依赖：

uv add --script demo.py requests rich

然后运行：

uv run demo.py

uv 会根据脚本头部的 inline metadata 自动准备隔离环境。

如果只是临时运行一个带依赖的脚本，也可以不写入脚本元数据：

uv run --with rich demo.py

这种方式适合一次性测试；如果脚本要长期保留，建议用 uv add --script 把依赖写进脚本。

9. 使用 uvx 运行 Python 命令行工具

uvx 可以理解为“临时运行一个 Python 命令行工具”。它是 uv tool run 的简写。

比如临时运行 Ruff：

uvx ruff check .

临时运行指定版本：

uvx ruff@latest check .

如果包名和命令名不一致，可以用 --from。例如 http 命令来自 httpie 包：

uvx --from httpie http --version

如果某个工具经常用，就安装成用户级工具：

uv tool install ruff

安装后可以直接运行：

ruff --version

升级某个工具：

uv tool upgrade ruff

升级所有工具：

uv tool upgrade --all

查看已安装工具：

uv tool list

这里要注意：uv tool install 安装的是命令行工具，不等于把包安装进当前项目环境。如果你想在项目代码里 import 某个库，应该用 uv add 或 uv pip install。

10. 兼容 pip 的用法

老项目里经常只有 requirements.txt，这时可以先使用 uv 的 pip 兼容接口。

创建虚拟环境：

uv venv

Linux / WSL 激活：

source .venv/bin/activate

Windows 激活：

.venv\Scripts\activate

安装包：

uv pip install flask

安装 requirements：

uv pip install -r requirements.txt

同步 requirements，也就是让环境尽量和 requirements 保持一致：

uv pip sync requirements.txt

导出当前环境：

uv pip freeze > requirements.txt

查看包列表：

uv pip list

检查依赖冲突：

uv pip check

卸载包：

uv pip uninstall flask

如果你只是想把原来的 pip 命令换成更快的实现，uv pip 会很顺手；如果你准备长期维护项目，建议逐步迁移到 pyproject.toml + uv.lock 的项目模式。

11. 从 requirements.txt 迁移到 uv 项目

假设老项目结构是：

old-project/
├── app.py
└── requirements.txt

可以这样迁移：

cd old-project
uv init
uv add -r requirements.txt
uv run python app.py

之后建议把 pyproject.toml 和 uv.lock 提交到 Git：

git add pyproject.toml uv.lock .python-version
git commit -m "migrate dependencies to uv"

以后新机器拉项目后：

uv sync
uv run python app.py

就能尽量复现同一套依赖环境。

12. 国内网络和服务器使用建议

在国内服务器上，uv 本身的安装脚本、Python 下载、PyPI 依赖下载都可能受到网络影响。可以按下面思路处理。

12.1 安装 uv 慢或失败

先试官方脚本：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果失败，可以改用 PyPI 方式：

pipx install uv

或者：

pip install uv

Windows 也可以尝试：

winget install --id=astral-sh.uv -e

12.2 依赖下载慢：临时指定镜像源

uv 新版本推荐用 --default-index 指定默认 Python 包索引。例如：

uv add fastapi --default-index https://pypi.tuna.tsinghua.edu.cn/simple

pip 兼容模式也可以：

uv pip install fastapi --default-index https://pypi.tuna.tsinghua.edu.cn/simple

PowerShell 临时设置环境变量：

$env:UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

Linux / WSL 临时设置环境变量：

export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

12.3 公司代理或证书环境

如果公司网络里有代理、HTTPS 中间证书、私有 CA，遇到 TLS 证书问题时，可以关注：

uv --system-certs ...

或环境变量：

UV_SYSTEM_CERTS=1

这个选项会让 uv 使用系统证书存储。注意，只有在你确实信任当前系统证书链时才应该这么做。

13. 缓存管理

uv 的速度很大一部分来自缓存和依赖复用。常用命令：

查看缓存目录：

uv cache dir

查看缓存大小：

uv cache size

清理缓存：

uv cache clean

清理不常用的缓存：

uv cache prune

一般不需要频繁清理缓存。服务器磁盘紧张，或者构建环境出现奇怪的缓存问题时，再考虑清理。

14. 常用命令速查

目标 命令
查看 uv 版本 uv --version
新建项目 uv init my-project
在当前目录初始化项目 uv init
添加依赖 uv add requests
删除依赖 uv remove requests
同步项目环境 uv sync
运行项目命令 uv run python main.py
生成/更新锁文件 uv lock
查看依赖树 uv tree
创建虚拟环境 uv venv
pip 方式安装包 uv pip install flask
同步 requirements uv pip sync requirements.txt
安装 Python uv python install 3.12
查看 Python 版本 uv python list
固定项目 Python uv python pin 3.12
临时运行工具 uvx ruff check .
安装工具 uv tool install ruff
升级 uv uv self update
查看缓存目录 uv cache dir
清理缓存 uv cache clean

15. 我的使用建议

如果是新项目，直接用这一套就够了：

uv init myapp
cd myapp
uv python pin 3.12
uv add fastapi uvicorn
uv run python main.py

如果是老项目，先别急着改结构，可以从 pip 兼容模式开始：

uv venv
uv pip install -r requirements.txt
uv pip check

如果要跑命令行工具，不要污染项目环境：

uvx ruff check .
uvx black .

如果是服务器部署，建议把这些文件提交到仓库：

pyproject.toml
uv.lock
.python-version

部署时使用：

uv sync --frozen
uv run python main.py

这样比“在服务器上手工 pip install 一堆包”更可控。

16. 常见问题

Q1：uv 能完全替代 pip 吗？

大多数日常安装、同步、查看、检查依赖的工作可以用 uv pip 完成。但 uv 不只是 pip 的加速版，它更推荐使用项目模式管理依赖。

Q2：uv 和 poetry 怎么选？

如果你喜欢 Poetry 的项目管理体验，但又希望安装和解析更快，可以试试 uv。uv 的命令更偏工程化和组合式，uv run、uv sync、uv lock 的心智模型比较适合团队项目。

Q3：Windows 和 WSL 要不要共用一个 uv？

不建议。Windows 装 Windows 版，WSL 装 Linux 版。两边独立管理，路径问题更少。

Q4：uv 会不会影响系统 Python？

默认情况下，uv 更鼓励虚拟环境和项目环境，不建议直接修改系统 Python。只有你明确使用 --system 等选项时，才会进入系统环境相关场景。

Q5：uv.lock 要不要提交？

应用项目一般建议提交。它能让团队成员、CI 和服务器尽量使用一致的依赖解析结果。

参考资料

  • uv 官方文档：https://docs.astral.sh/uv/
  • uv 安装文档：https://docs.astral.sh/uv/getting-started/installation/
  • uv 功能概览：https://docs.astral.sh/uv/getting-started/features/
  • uv 项目使用指南：https://docs.astral.sh/uv/guides/projects/
  • uv 脚本使用指南：https://docs.astral.sh/uv/guides/scripts/
  • uv 工具使用指南：https://docs.astral.sh/uv/guides/tools/
  • uv Python 版本管理：https://docs.astral.sh/uv/guides/install-python/
  • uv pip 兼容接口：https://docs.astral.sh/uv/pip/environments/
  • uv CLI 参考：https://docs.astral.sh/uv/reference/cli/