uv 使用手册（Linux & Windows）
—— 现代 Python 版本 + 包 + 项目管理一站式工具
uv 是 Astral 团队开发的 Rust 工具，被誉为 Python 生态的“瑞士军刀”。它能极大替代 pyenv + venv + pip + pip-tools + pipx 等工具，速度极快（通常 10-100x pip）。
1. 安装 uv
Linux 安装（推荐独立安装器）
curl -LsSf https://astral.sh/uv/install.sh | sh
或者使用 wget：
wget -qO- https://astral.sh/uv/install.sh | sh
Windows 安装（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后：
- 重新打开终端
- 检查版本：
uv --version
更新 uv（独立安装方式）：
uv self update
2. Python 版本管理（类似 pyenv）
查看可用 Python
uv python list
安装 Python 版本
# 安装最新版
uv python install# 安装指定版本
uv python install 3.12
uv python install 3.11 3.12 3.13# 安装特定补丁版本
uv python install 3.12.8
切换 / 固定版本
# 项目目录下固定版本（推荐）
uv python pin 3.12 # 生成 .python-version 文件# 全局默认版本
uv python pin --global 3.12# 查看已安装版本
uv python list --installed
使用特定版本运行
uv run --python 3.12 python script.py
3. 项目管理（推荐方式）
初始化新项目
uv init myproject
cd myproject
添加依赖
uv add requests
uv add "requests>=2.32" # 指定版本
uv add ruff --dev # 开发依赖
uv add --group test pytest # 自定义组
同步环境（强烈推荐）
uv sync # 安装/更新依赖，生成 .venv
uv sync --frozen # 只使用 lockfile，不更新解析
运行命令（无需手动激活 venv）
uv run python main.py
uv run ruff check .
uv run pytest
锁定依赖
uv lock # 生成/更新 uv.lock
移除依赖
uv remove requests
4. 虚拟环境操作
uv venv # 在当前目录创建 .venv
uv venv myenv # 指定名称
uv venv --python 3.11 # 指定 Python 版本# 手动激活（传统方式）
# Linux
source .venv/bin/activate# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# 或 CMD
.venv\Scripts\activate.bat
提示：大多数情况下直接用 uv run 即可，无需激活。
5. 包管理（pip 兼容模式）
uv pip install numpy pandas
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt# 同步（类似 pip-sync）
uv pip sync requirements.txt
6. 工具管理（类似 pipx）
# 临时运行工具
uvx ruff check .
uvx pycowsay "Hello uv!"# 全局安装工具
uv tool install ruff
uv tool install black# 查看已安装工具
uv tool list
7. 常用命令速查表
| 类别 | 命令 | 说明 |
|---|---|---|
| Python 版本 | uv python install 3.12 |
安装 Python |
| Python 版本 | uv python pin 3.12 |
项目固定版本 |
| 项目初始化 | uv init |
创建新项目 |
| 添加依赖 | uv add <pkg> |
添加生产依赖 |
| 同步环境 | uv sync |
安装所有依赖 |
| 运行 | uv run <cmd> |
在项目环境中运行 |
| 锁定 | uv lock |
更新 uv.lock |
| 虚拟环境 | uv venv |
创建虚拟环境 |
| 工具 | uvx <tool> 或 uv tool run |
临时运行工具 |
| 工具安装 | uv tool install <tool> |
全局安装 CLI 工具 |
| 更新 uv | uv self update |
更新自身 |
8. Linux & Windows 差异注意事项
- 路径：Linux 使用
.venv/bin/python，Windows 使用.venv\Scripts\python.exe - 激活脚本：Windows PowerShell 推荐使用
Activate.ps1 - 权限：Linux 建议将
~/.local/bin加入 PATH；Windows 安装器会自动处理 - 性能：两者性能几乎一致，uv 的缓存跨平台共享
- Shell 补全：安装后可配置（
uv generate-shell-completion）
9. 最佳实践建议
- 新项目统一使用
uv init+uv add+uv sync - 始终提交
uv.lock和.python-version - 团队协作 时大家安装相同 uv 版本
- CI/CD 中可直接用 standalone 安装 uv
- 结合 VS Code：安装 Python 扩展，自动识别
.venv
官方文档：https://docs.astral.sh/uv/
GitHub：https://github.com/astral-sh/uv