1. 什么是 uv？ #

1.1 核心功能 #

功能 传统方式 uv
包管理 pip 内置
虚拟环境 venv 内置，自动管理
依赖锁定 pip-tools 内置 uv.lock
项目初始化 手动创建 uv init
运行脚本 需先激活环境 uv run

1.2 核心特点 # 

# 传统方式
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# uv 方式
uv sync

2. 为什么需要 uv？ #

2.1 速度对比 #

操作 pip + venv uv
创建虚拟环境 5–10 秒 1–2 秒
安装 pandas 2–3 分钟 10–20 秒
安装大型项目 5–10 分钟 30–60 秒

2.2 适用场景 #

不适合：需要管理 CUDA、MKL 等非 Python 依赖时，仍应使用 Conda。

3. 前置知识 #

3.1 pyproject.toml #

pyproject.toml 是 Python 项目的现代配置文件（TOML 格式），声明项目元数据和依赖：

[project]  # 项目信息配置节
name = "my-project"  # 项目名称
version = "0.1.0"  # 项目版本
requires-python = ">=3.10"  # 要求的 Python 版本
dependencies = [  # 项目所需依赖列表
    "requests>=2.25",  # 依赖 requests，需 2.25 及以上版本
    "pandas>=1.5",     # 依赖 pandas，需 1.5 及以上版本
]

[project.optional-dependencies]  # 可选依赖配置节
dev = [  # 名为 dev 的可选依赖
    "pytest>=7.0",  # 测试依赖 pytest，需 7.0 及以上版本
]

3.2 uv.lock 锁文件 #

uv.lock 精确记录所有直接和间接依赖的版本，确保任何人在任何时间 uv sync 都得到相同环境。

4. 安装 uv #

4.1 Windows（PowerShell） # 

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

如果 PowerShell 提示执行策略限制，运行以下命令：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

该命令允许当前用户运行本地及受信任的脚本，无需管理员权限，可解决“禁止运行脚本”的报错。

4.2 macOS / Linux # 

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc   # 或 source ~/.zshrc
uv --version

4.3 备选安装方式 # 

pip install uv          # 可用，但不如官方脚本新
brew install uv         # macOS Homebrew

5. 创建第一个项目 #

5.1 完整演示 # 

# 1. 创建项目
uv init my-first-project
cd my-first-project

# 2. 添加依赖
uv add requests

# 3. 查看 pyproject.toml（requests 已自动写入 dependencies）
type pyproject.toml        # Windows
# cat pyproject.toml       # macOS/Linux

# 4. 创建测试脚本 test.py
# test.py
import requests

response = requests.get('https://www.example.com')
print(f"状态码：{response.status_code}")
# 5. 运行（无需激活虚拟环境）
uv run python test.py

# 6. 查看已安装的包
uv pip list

预期输出：

状态码：200

5.2 团队协作 #

其他成员克隆项目后：

uv sync
uv run python test.py

6. uv 核心命令 #

6.1 项目管理 # 

uv init my-project          # 创建新项目
uv init .                     # 在当前目录初始化
uv init --python 3.10 my-project  # 指定 Python 版本

uv sync                       # 同步依赖（读 pyproject.toml + uv.lock）
uv sync --upgrade               # 升级所有依赖
uv lock                         # 只更新锁文件，不安装

6.2 包管理 # 

uv add requests                 # 添加依赖
uv add "requests==2.31.0"       # 指定版本
uv add requests pandas numpy    # 同时添加多个

uv add --dev pytest             # 添加开发依赖
uv remove requests              # 移除依赖

uv pip list                     # 查看已安装包
uv pip show requests            # 查看包信息

6.3 运行命令 # 

uv run script.py         # 运行脚本
uv run python script.py         # 运行脚本
uv run python -m pytest         # 运行模块

6.4 pip 兼容命令 # 

uv pip install requests                           # 安装（不写入 pyproject.toml）
uv pip install -r requirements.txt              # 从 requirements.txt 安装
uv pip freeze > requirements.txt                  # 导出依赖
uv pip uninstall requests                         # 卸载

7. pyproject.toml 基础 #

7.1 常用字段 #

字段 说明 示例
name 项目名称 "my-project"
version 版本号 "0.1.0"
requires-python Python 版本要求 ">=3.10"
dependencies 生产依赖 ["requests>=2.25"]
optional-dependencies 可选依赖组 dev = ["pytest>=7.0"]

7.2 版本写法 # 

dependencies = [
    "requests==2.31.0",       # 精确版本
    "pandas>=1.5,<2.0",       # 版本范围
]

7.3 安装可选依赖组 # 

uv sync --extra dev     # 安装 dev 组依赖

8. 完整工作流程 # 

# 1. 创建项目
uv init web-api
cd web-api

# 2. 添加依赖
uv add fastapi uvicorn requests
uv add --dev pytest

# 3. 编写 main.py 后运行
uv run uvicorn main:app --reload

# 4. 运行测试
uv run pytest

main.py

# 从fastapi模块中导入FastAPI类
from fastapi import FastAPI

# 创建一个FastAPI应用实例
app = FastAPI()

# 使用GET方法注册根路径"/"的路由
@app.get("/")
# 定义处理根路径请求的函数
def read_root():
    # 返回一个包含问候语的JSON响应
    return {"message": "Hello from web-api!"}

推荐项目结构：

web-api/
├── .venv/           # 虚拟环境（不提交 Git）
├── main.py          # 项目代码
├── pyproject.toml   # 项目配置（提交 Git）
├── uv.lock          # 锁文件（提交 Git）
└── .gitignore

团队成员使用：

git clone <项目地址>
cd web-api
uv sync
uv run uvicorn main:app --reload

9. 配置镜像加速 #

9.1 方法一：配置文件（推荐） #

Windows 配置文件路径： %APPDATA%\uv\uv.toml

Linux/macOS 配置文件路径： ~/.config/uv/uv.toml

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
default = true

9.2 方法二：环境变量（临时） # 

# Windows PowerShell
$env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple/"

# Windows CMD
set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
# macOS/Linux
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple/"

9.3 常用国内镜像 #

10. 常见问题 #

10.1 uv 命令找不到 # 

# 重启终端后验证
uv --version

# 若仍失败，检查安装路径是否在 PATH 中
# Windows 默认：C:\Users\<用户名>\.local\bin

10.2 与现有 requirements.txt 项目兼容 # 

# 方式一：直接用 uv pip 安装
uv pip install -r requirements.txt

# 方式二：迁移到 pyproject.toml
uv init .
# 手动将依赖写入 pyproject.toml，或用 uv add 逐个添加
uv sync

10.3 Failed to hardlink files 警告 #

跨磁盘（如缓存在 C 盘、项目在 D 盘）时可能出现此警告，功能正常，可安全忽略：

set UV_LINK_MODE=copy

或将缓存目录设到同一磁盘：

set UV_CACHE_DIR=D:\uv_cache

10.4 VSCode CodeRunner 使用 uv # 

{
    "code-runner.executorMap": {
        "python": "set PYTHONIOENCODING=utf8 && uv run $fullFileName"
    }
}

11. 总结 #

11.1 最常用命令 # 

uv --version                          # 检查版本
uv init project-name                  # 创建项目
uv add package-name                   # 添加依赖
uv add --dev pytest                   # 添加开发依赖
uv remove package-name                # 移除依赖
uv sync                               # 同步依赖
uv sync --upgrade                     # 升级所有依赖
uv run python script.py               # 运行脚本
uv pip list                           # 查看已安装包
uv pip install -r requirements.txt    # 兼容 requirements.txt
uv lock                               # 更新锁文件

11.2 最佳实践 #

11.3 核心概念 #

概念 说明
uv 极速 Python 包管理与项目工作流工具
pyproject.toml 项目配置与依赖声明文件
uv.lock 精确锁定所有依赖版本的锁文件
uv run 在项目环境中运行命令，无需激活环境
← 上一节 39.venv 下一节 41.typing →