uv 安装和使用教程

uv 是 Astral 开发的 Python 包和项目管理工具。它可以替代一部分 pip、pip-tools、pipx、poetry、pyenv 的工作，用来安装依赖、管理虚拟环境、锁定版本、运行命令，也可以安装和切换 Python 版本。

它最大的优点是速度快、命令统一、项目体验比较完整。对于新项目，可以直接用 uv 管理；对于已有项目，也可以逐步引入。

安装 uv

macOS 和 Linux 可以使用官方安装脚本：

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

如果没有 curl，也可以用 wget：

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

Windows PowerShell 使用：

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

macOS 或 Linux 如果已经安装 Homebrew，也可以用：

1
brew install uv

Python 用户还可以通过 pipx 安装：

1
pipx install uv

安装完成后，重新打开终端，检查版本：

1
uv --version

如果提示找不到 uv，通常是安装目录还没有加入 PATH，可以重新打开终端，或者按安装脚本最后的提示加载 shell 配置。

创建新项目

创建一个新项目：

1
uv init demo
2
cd demo

uv 会生成基础项目文件，比如 pyproject.toml。这是现代 Python 项目常用的配置文件，用来记录项目名称、版本、依赖和构建配置。

查看项目结构：

1
ls

一般会看到类似这些文件：

1
README.md
2
main.py
3
pyproject.toml

添加依赖

添加运行时依赖：

1
uv add requests

添加开发依赖，例如测试工具：

1
uv add --dev pytest

uv 会自动解析依赖，创建或更新虚拟环境，并生成锁文件 uv.lock。这个锁文件应该提交到 Git，方便其他环境安装到一致的依赖版本。

运行项目命令

使用 uv 运行 Python 文件：

1
uv run python main.py

运行安装在项目环境里的命令：

1
uv run pytest

运行格式化或检查工具：

1
uv run ruff check

uv run 会自动使用当前项目的虚拟环境。如果环境还没创建，uv 会按项目配置先创建环境并安装依赖。

同步依赖环境

克隆一个已有 uv 项目后，进入项目目录执行：

1
uv sync

这会根据 pyproject.toml 和 uv.lock 同步依赖环境。

如果是在 CI 或部署环境中，希望严格按照锁文件安装，可以使用：

1
uv sync --locked

常见的 CI 流程通常是：

1
uv sync --locked
2
uv run pytest

更新锁文件

手动解析并更新锁文件：

1
uv lock

如果只想升级某个包，可以先更新依赖声明，再重新锁定：

1
uv add requests
2
uv lock

移除依赖

移除依赖：

1
uv remove requests

移除开发依赖：

1
uv remove --dev pytest

管理 Python 版本

uv 可以安装 Python 版本：

1
uv python install 3.12

也可以一次安装多个版本：

1
uv python install 3.12 3.13

查看本机可用的 Python：

1
uv python list

创建项目时指定 Python 版本：

1
uv init demo --python 3.12

在已有项目中使用指定版本运行：

1
uv run --python 3.12 python --version

使用 .python-version

如果项目需要固定 Python 版本，可以在项目根目录放一个 .python-version 文件：

1
3.12

之后在项目里执行：

1
uv sync

uv 会优先按项目要求选择 Python 版本。如果本机没有对应版本，可以先执行：

1
uv python install 3.12

安装命令行工具

uv 也可以像 pipx 一样安装独立命令行工具。

安装 ruff：

1
uv tool install ruff

查看版本：

1
ruff --version

临时运行一个工具，不长期安装：

1
uvx ruff check .

uvx 适合偶尔使用某个工具，不想把它安装进当前项目，也不想全局长期保留。

和 pip 的区别

pip 主要负责安装 Python 包，而 uv 覆盖的范围更大：

1
pip        安装包
2
venv       创建虚拟环境
3
pip-tools  锁定依赖
4
pipx       安装命令行工具
5
pyenv      管理 Python 版本
6
poetry     管理项目依赖和锁文件

uv 不是简单替代某一个工具，而是把这些常见工作整合到一个命令体系里。

已有项目如何迁移

如果项目已经有 requirements.txt，可以先创建虚拟环境并安装：

1
uv venv
2
uv pip install -r requirements.txt

如果准备改成 uv 项目管理方式，可以逐步迁移到 pyproject.toml：

1
uv init
2
uv add flask
3
uv add --dev pytest

迁移时不建议一次性重构所有配置。先让依赖安装和测试命令跑通，再逐步整理项目结构。

常用命令速查

1
uv --version                 # 查看 uv 版本
2
uv init demo                 # 创建新项目
3
uv add requests              # 添加依赖
4
uv add --dev pytest          # 添加开发依赖
5
uv remove requests           # 移除依赖
6
uv sync                      # 同步依赖环境
7
uv sync --locked             # 严格按锁文件同步
8
uv lock                      # 更新锁文件
9
uv run python main.py        # 在项目环境中运行命令
10
uv python install 3.12       # 安装 Python 3.12
11
uv python list               # 查看 Python 版本
12
uv tool install ruff         # 安装命令行工具
13
uvx ruff check .             # 临时运行工具

常见问题

uv: command not found

先重新打开终端。如果还不行，检查安装脚本输出的提示，确认 uv 的安装目录已经加入 PATH。

是否还需要手动激活虚拟环境

大多数情况下不需要。优先使用：

1
uv run python main.py

如果确实想手动激活，也可以：

1
source .venv/bin/activate

Windows PowerShell 通常是：

1
.venv\Scripts\Activate.ps1

uv.lock 要不要提交

建议提交。uv.lock 用来锁定依赖版本，能减少“我这里能跑，你那里不能跑”的问题。

什么时候用 uvx

临时运行工具时用 uvx，例如偶尔跑一次：

1
uvx ruff check .

如果这个工具是项目长期需要的开发依赖，更适合：

1
uv add --dev ruff
2
uv run ruff check .

总结

uv 适合把 Python 版本、虚拟环境、依赖安装和锁文件管理放到同一套工作流里。新项目可以直接用 uv init 开始，已有项目可以逐步从 requirements.txt 或 pip 迁移到 pyproject.toml 和 uv.lock，先保证可复现，再逐步替换日常命令。

如果你只是想先解决下载慢的问题，可以先看 pip 源的设置和使用；如果还需要管理 Node.js 版本，可以对照 nvm 安装和使用教程；如果已经准备用 uv 管理脚本、workspace 和工具链，可以继续阅读 uv 进阶：脚本、工作区与工具链实战。版本变化建议以 uv 官方文档 为准。