uv 是一个由 Astral（原 hatch 项目团队）开发的全新、极快的 Python 包管理工具。它兼具以下功能：
- 依赖解析：比 pip 更快、更可靠，支持锁文件 (uv lock)。
- 虚拟环境创建：可以在几毫秒内生成隔离的 Python 环境（类似 venv、virtualenv、conda）。
- 包安装/卸载：使用 uv pip install … 语法，兼容现有 pip 参数。
- 跨平台：支持 Windows、macOS、Linux，并提供单二进制文件（无需额外依赖）。
注意：截至 2025 年，uv 已经在 PyPI 上正式发布 (uv==0.4.x) 并且可以直接通过 pip install uv 或使用官方安装脚本进行部署。
一、准备工作
1 安装 uv
方法 A：使用 pip（最常见）
# 推荐在系统的全局 Python 环境中执行
python -m pip install --upgrade uv
如果你已经有 pip，这一步只需要几秒钟。
方法 B：官方二进制安装脚本（适合没有 pip 的环境）
curl -LsSf https://install.uv.run | sh
# 或者在 Windows PowerShell:
iwr https://install.uv.run -UseBasicParsing | iex
该脚本会把 uv 放到 $HOME/.local/bin（Linux/macOS）或 %USERPROFILE%\AppData\Local\Programs\uv（Windows），记得将其加入系统 PATH。
2 验证安装
uv --version
# 示例输出: uv 0.4.3
如果出现版本号，说明 uv 已经可用。
二、使用 uv 创建虚拟环境
uv 的核心命令是 uv venv（或者简写为 uv env），它会在指定目录下生成一个完整的 Python 虚拟环境。
1 基本语法
uv venv <target-dir>
- <target-dir>：你希望虚拟环境所在的路径。可以是相对路径或绝对路径。
- 若目标目录不存在，uv 会自动创建它。
默认行为 - 使用系统当前 Python 解释器（即 python 命令指向的版本）作为基础。 - 环境结构与标准 venv 完全兼容：包含 bin/ (Linux/macOS) 或 Scripts/ (Windows)、lib/、include/ 等。
示例
# 在当前项目根目录下创建名为 .venv 的虚拟环境
uv venv .venv
执行后，你会看到类似以下结构：
.project/
│─ src/
│─ tests/
│─ .venv/
│─ bin/ (或 Scripts/)
├─ python
├─ pip
└─ uv
│─ lib/
│─ include/
└─ pyvenv.cfg
pyvenv.cfg 中记录了基准 Python 版本和 uv 的路径，供后续工具读取。
2 指定 Python 解释器
如果你想用特定的 Python 版本（比如 python3.11），可以使用 --python 参数：
uv venv .venv --python /usr/bin/python3.11
# 或者在 Windows:
uv venv .venv --python C:\Python311\python.exe
uv 会检查该解释器是否可用，并在创建环境时复制对应的标准库。
3 自定义环境名称 & 位置
- 自定义目录：任意路径均可，例如 /opt/myproject/env。
- 一次性创建并激活（仅在 Unix 系统下）：
source $(uv venv .venv --quiet)/bin/activate
--quiet 让 uv 只输出环境根目录路径，便于脚本化使用。
4 环境的可重复性
如果你在 CI/CD 或团队协作中需要保证所有人使用相同的虚拟环境，可以把 .venv 目录加入到项目仓库（不推荐），或者更好地使用 uv lock + uv sync（后面会介绍）。
三、在虚拟环境中安装依赖
1 激活环境（手动）
Linux/macOS：
source .venv/bin/activate # 或者: . .venv/bin/activate
Windows (PowerShell)：
. .venv\Scripts\Activate.ps1
# CMD:
.\venv\Scripts\activate.bat
激活后，终端提示会变成 (venv) 前缀，所有 python、pip 调用都会指向该环境。
2 使用 uv pip 安装
uv 自带一个兼容 pip 的子命令，可直接在已激活的环境中使用：
uv pip install requests==2.31.0
与原生 pip 相比，uv pip 在依赖解析、下载速度上更快。
3 自动创建并安装（无需手动激活）
如果你不想每次都 source activate，可以直接在命令中指定环境路径：
# 创建 .venv 并一次性安装所有需求
uv venv .venv && uv pip install -r requirements.txt --target .venv
这里的 --target 参数让 uv pip 将包直接放入
.venv/lib/pythonX.Y/site-packages/，等价于在激活后执行 pip install.
四、锁定依赖 & 同步环境（推荐工作流）
1 创建锁文件
# 在项目根目录生成 uv.lock (类似 Pipfile.lock)
uv lock -r requirements.txt
- requirements.txt 是你的需求列表（可以是普通的 pip freeze 输出）。
- uv lock 会解析所有依赖、递归获取子依赖，并记录 精确版本 + hash，确保跨平台可重复安装。
2 同步虚拟环境
# 假设已有 .venv（或新建），使用锁文件同步：
uv sync .venv
- uv sync 会读取当前目录的 uv.lock，并在指定的虚拟环境中 安装/更新 所有包至锁定版本。
- 若 .venv 不存在，uv sync 会自动创建它。
3 完整 CI 示例（GitHub Actions）
name: Python CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
run: python -m pip install --upgrade uv
- name: Sync virtual env
run: |
uv sync .venv # 自动创建并安装锁定依赖
source .venv/bin/activate
python -m pytest
通过 uv lock + uv sync，每次 CI 都使用完全相同的依赖版本，避免 “works on my machine” 的问题。
五、常用选项与技巧
命令 | 常见参数 | 功能说明 |
uv venv | --python <path> | 指定基础解释器 |
--quiet | 只输出环境根路径（便于脚本） | |
--no-pip | 创建环境但不自动安装 pip (rare) | |
uv pip install | -r <file> | 从 requirements.txt 安装 |
--target <env> | 指定目标虚拟环境目录 | |
--upgrade | 升级已安装的包 | |
uv lock | -r <requirements> | 生成锁文件 |
--output <file> | 自定义锁文件名 | |
uv sync | <env-dir> | 同步/创建虚拟环境至锁定状态 |
--no-clean | 不删除未在 lock 中的包（保留旧包） |
小技巧
- 一次性创建+激活脚本
- # Bash 一行命令，创建 .venv 并立即激活
source $(uv venv .venv --quiet)/bin/activate
- 在项目根目录放置 uv.lock 与 .gitignore
- 将 uv.lock 加入版本控制（确保团队统一）。把 .venv/ 添加到 .gitignore，避免把大体积的虚拟环境提交。
- 使用 uv run 直接执行脚本（不必手动激活）
- uv run --venv .venv my_script.pyuv run 会在后台创建/激活指定虚拟环境并运行 Python 脚本。
六、常见问题 & FAQ
问题 | 解答 |
我已经有 virtualenv，为什么要换成 uv？ | uv 的依赖解析速度快 5-10 倍；创建虚拟环境几乎瞬间完成；统一的 CLI（uv venv, uv pip, uv lock, uv sync) 简化工作流。 |
在 Windows PowerShell 中激活失败？ | 确保执行 .\venv\Scripts\Activate.ps1，并且 PowerShell 已允许运行脚本 (Set-ExecutionPolicy RemoteSigned -Scope CurrentUser). |
uv sync 报错 “No lock file found”。 | 必须先运行 uv lock（或手动创建 uv.lock），锁文件默认位于项目根目录。 |
如何切换到不同 Python 版本的虚拟环境？ | 删除旧 .venv（rm -rf .venv）后使用 uv venv .venv --python /path/to/pythonX.Y. |
uv 与 pip 冲突吗？ | uv pip 完全兼容 pip 参数；在同一环境中可以同时使用两者，但建议统一使用 uv pip 以获得更快解析。 |
七、完整示例：从零到可部署的项目
# 1 安装 uv（一次性）
python -m pip install --upgrade uv
# 2 初始化项目结构
mkdir myproject && cd myproject
touch main.py requirements.txt
# 3 编写需求文件 (示例)
cat > requirements.txt <<EOF
requests>=2.28
numpy==1.26.4
pandas~=2.2
EOF
# 4 创建锁文件（确保依赖固定）
uv lock -r requirements.txt # 生成 uv.lock
# 5 同步虚拟环境 (自动创建)
uv sync .venv # 基于 uv.lock 安装所有包
# 6 编写代码 (示例)
cat > main.py <<EOF
import requests, numpy as np, pandas as pd
print("All packages loaded successfully!")
EOF
# 7 运行脚本（无需手动激活）
uv run --venv .venv main.py # 输出: All packages loaded successfully!
这套流程可以直接复制到 CI 脚本、Dockerfile 或者任何自动化工具中，实现 快速、可重复 的 Python 环境管理。
小结
- uv 是现代化的、极速的 Python 包/环境管理工具。
- 使用 uv venv 创建虚拟环境几乎瞬间完成，支持自定义解释器。
- 通过 uv lock + uv sync 可以锁定依赖，实现跨机器、CI 环境的一致性。
- 与传统 venv / virtualenv 完全兼容，且提供统一的 CLI，使项目维护更简洁。
如果你已经熟悉 pip/venv，只需把相应命令替换为 uv venv, uv pip, uv lock, uv sync 即可获得显著的性能提升和更可靠的依赖管理。祝你开发顺利！