uv 是 Astral 开发的 Python 项目与包管理工具，基于 Rust 构建。它将解释器下载、虚拟环境配置、依赖安装和锁文件管理整合到了单一二进制文件中，可以直接替代 pip、virtualenv、pyenv 和 Poetry。

一、安装 uv

macOS 与 Linux：

1
2
3
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或通过 Homebrew 安装
brew install uv

Windows (PowerShell)：

1
2
3
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或通过 winget 安装
winget install --id=astral-sh.uv

安装后重新打开终端，验证安装情况：

1
uv --version

二、管理 Python 版本

uv 内置跨平台的 Python 解释器下载功能，无需在操作系统中预先安装 Python。

查看本地已安装及线上可选的版本：

1
uv python list

下载并安装指定版本：

1
uv python install 3.10 3.11 3.12

卸载特定版本：

1
uv python uninstall 3.10

直接调用指定版本执行命令：

1
uv run --python 3.12 python -c "import sys; print(sys.version)"

三、虚拟环境与依赖管理

uv 支持两种使用模式：

  1. 项目工作流：使用 pyproject.toml 与 uv.lock 统一管理依赖与环境，免去手动激活虚拟环境的步骤。
  2. 独立虚拟环境：沿用传统的 venv 与 pip 模式，适合轻量脚本或存量项目过渡。

1. 项目工作流

初始化新项目：

1
2
uv init my_project
cd my_project

执行后会自动生成项目结构，包括 pyproject.toml（依赖配置）、.python-version（当前锁定版本）和 main.py（入口代码）。

绑定当前项目的 Python 版本：

1
uv python pin 3.11

添加与移除依赖（uv 会自动同步到 .venv，无需手动激活）：

1
2
3
4
5
6
7
8
# 添加运行依赖，自动写入 pyproject.toml 并刷新 uv.lock
uv add requests fastapi

# 添加开发期依赖
uv add --dev pytest ruff

# 移除依赖
uv remove requests

运行代码与测试：
使用 uv run 可以在当前项目的隔离环境中执行脚本，系统会自动确认依赖完整性。

1
2
uv run python main.py
uv run pytest

在团队成员间同步环境：
拉取代码后，根据锁文件还原一致的虚拟环境：

1
uv sync

2. 独立虚拟环境工作流

如果只需要在任意目录手动建立一个虚拟环境：

创建虚拟环境：

1
2
3
4
5
6
7
8
# 使用系统默认 Python 创建 .venv
uv venv

# 指定 Python 版本
uv venv --python 3.11

# 自定义目录名称
uv venv myenv

激活虚拟环境：

  • macOS / Linux: source .venv/bin/activate
  • Windows: .venv\Scripts\activate

安装与管理包：

1
2
3
4
5
6
7
8
# 安装单个或多个包
uv pip install numpy pandas

# 通过 requirements.txt 安装
uv pip install -r requirements.txt

# 导出当前环境依赖清单
uv pip freeze > requirements.txt

四、直接运行 Python CLI 工具

通过 uvx（等同于 uv tool run），可以在隔离的临时环境中运行命令行工具，不需要全局安装到本地系统：

1
2
3
4
5
6
7
8
# 临时运行 ruff 检查代码
uvx ruff check .

# 临时启动 httpie
uvx httpie GET https://api.github.com

# 运行测试脚本工具
uvx pycowsay "Hello uv"

五、配置镜像源

临时指定源：

1
uv add requests --index-url https://mirrors.aliyun.com/pypi/simple/

通过环境变量配置全局默认源：

  • Linux / macOS（写入 ~/.bashrc 或 ~/.zshrc）：
    1
    export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"
  • Windows PowerShell：
    1
    [Environment]::SetEnvironmentVariable("UV_DEFAULT_INDEX", "https://mirrors.aliyun.com/pypi/simple/", "User")

旧版本使用的 UV_INDEX_URL 已被标记为弃用，目前仍可使用，新配置建议用 UV_DEFAULT_INDEX。

为单个项目配置独立源：
在项目的 pyproject.toml 末尾补充：

1
2
3
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

六、常用命令速查

类别 命令 说明
Python 版本 uv python install <version> 下载并安装指定 Python 版本
uv python list 查看本地及远程可用 Python 版本
uv python pin <version> 将当前项目绑定至指定版本
项目依赖 uv init <name> 初始化 Python 项目
uv add <package> 添加依赖并写入 lock 文件
uv add --dev <package> 添加开发依赖
uv remove <package> 移除依赖项
uv sync 按照 uv.lock 同步当前环境
uv run <command> 在项目环境中执行脚本或命令
基础虚拟环境 uv venv 创建轻量虚拟环境
uv pip install <package> 安装指定 Python 包
独立工具 uvx <tool> [args] 在临时环境中执行 CLI 工具