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

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

安装 uv

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

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

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

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

Windows PowerShell 使用：

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

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

brew install uv

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

pipx install uv

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

uv --version

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

创建新项目

创建一个新项目：

uv init demo
cd demo

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

查看项目结构：

ls

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

README.md
main.py
pyproject.toml

添加依赖

添加运行时依赖：

uv add requests

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

uv add --dev pytest

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

运行项目命令

使用 uv 运行 Python 文件：

uv run python main.py

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

uv run pytest

运行格式化或检查工具：

uv run ruff check

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

同步依赖环境

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

uv sync

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

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

uv sync --locked

常见的 CI 流程通常是：

uv sync --locked
uv run pytest

更新锁文件

手动解析并更新锁文件：

uv lock

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

uv add requests
uv lock

移除依赖

移除依赖：

uv remove requests

移除开发依赖：

uv remove --dev pytest

管理 Python 版本

uv 可以安装 Python 版本：

uv python install 3.12

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

uv python install 3.12 3.13

查看本机可用的 Python：

uv python list

创建项目时指定 Python 版本：

uv init demo --python 3.12

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

uv run --python 3.12 python --version

使用 .python-version

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

3.12

之后在项目里执行：

uv sync

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

uv python install 3.12

安装命令行工具

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

安装 ruff：

uv tool install ruff

查看版本：

ruff --version

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

uvx ruff check .

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

和 pip 的区别

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

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

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

已有项目如何迁移

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

uv venv
uv pip install -r requirements.txt

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

uv init
uv add flask
uv add --dev pytest

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

常用命令速查

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

常见问题

uv: command not found

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

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

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

uv run python main.py

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

source .venv/bin/activate

Windows PowerShell 通常是：

.venv\Scripts\Activate.ps1

uv.lock 要不要提交

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

什么时候用 uvx

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

uvx ruff check .

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

uv add --dev ruff
uv run ruff check .