[!info] related notes

• 所属 MOC: python-moc, development-environment-moc
• 前置概念: virtualenv, poetry
• 并列概念: virtualenv, poetry
• 关系笔记: python-package-management-evolution
• 相关工具: cargo（uv 使用 Rust 编写）, ruff, pylance

uv

一句话定义

uv 是 Astral 公司（开发了著名的极速代码检查工具 Ruff 的团队）用 Rust 编写的极速 Python 工具链，是一个统一的 Python 工具链，旨在替代 pip、virtualenv、pyenv、pipx 甚至 Poetry。

核心内容

解决什么问题

传统 Python 工具链的问题：

• 速度慢：pip 依赖解析和安装速度慢
• 工具分散：pip、virtualenv、pyenv、pipx 各管各的
• 缺乏统一：不同工具配置方式不一致

四大角色

1. 包管理器 (Package Manager)：

• 完全兼容并替代 pip
• uv pip install requests 就是极速包管理器
• 支持 pyproject.toml 和 uv.lock 管理依赖

2. 环境管理器 (Environment Manager)：

• 替代 virtualenv 和 pyenv
• 自动下载不同版本的 Python 解释器
• 创建隔离的虚拟环境（.venv）

3. 项目管理器 (Project Manager)：

• 替代 Poetry 或 PDM
• 通过 pyproject.toml 和 uv.lock 管理整个项目生命周期
• 依赖解析和构建一体化

4. 工具运行器 (Tool Runner)：

• 替代 pipx
• uvx ruff 或 uv tool install httpie 运行全局命令行工具
• 不会污染系统环境

核心优势

快到离谱：

• Rust 编写 + 全局智能缓存
• 依赖解析和安装速度比传统工具快 10-100 倍
• CI/CD 构建时间大幅缩短

自带 Python 管理：

• 不需要提前安装 Python
• uv run 或 uv python install 自动下载对应 Python 版本
• 自动隔离运行

全面兼容：

• 兼容 pip API（uv pip install）
• 支持 pyproject.toml 和 lock 文件
• 可以像 Poetry 一样管理项目

统一工具链：

• 替代 pip（包安装）
• 替代 virtualenv（虚拟环境）
• 替代 pyenv（Python 版本管理）
• 替代 pipx（全局工具安装）
• 替代 Poetry（项目管理）

Python 版本选择建议（2026年）

黄金甜点位（强烈推荐）：3.12 或 3.13

• 性能优化明显
• 主流 AI 框架和 FastAPI 完美支持
• 3.13 引入实验性释放 GIL 功能

激进尝鲜版：3.14

• 纯 Python 代码没问题
• 可能遇到找不到预编译包（Wheels）的问题

步入暮年：3.11

• 依然坚挺，但新项目无需首选

尽力避免：3.10 及以下

• 官方维护停止（EOL）
• 存在安全风险，享受不到现代 Python 性能红利

最小例子

安装 uv

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

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

# 使用 pip
pip install uv

# 使用包管理器
# macOS
brew install uv
# Windows
scoop install uv

管理 Python 版本

# 安装 Python
uv python install 3.12

# 列出可用版本
uv python list

# 使用特定版本
uv python pin 3.12

创建项目

# 创建新项目
uv init my-project

# 项目结构
my-project/
├── pyproject.toml
├── hello.py
└── .python-version

管理依赖

# 添加依赖
uv add requests

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

# 安装所有依赖
uv sync

# 更新依赖
uv lock --upgrade

# 移除依赖
uv remove requests

运行项目

# 运行脚本
uv run python main.py

# 运行模块
uv run -m pytest

# 运行工具（无需安装）
uvx ruff check .

pip 兼容模式

# 像 pip 一样使用
uv pip install requests
uv pip list
uv pip freeze > requirements.txt

# 创建虚拟环境
uv venv

# 在虚拟环境中安装
uv pip install -r requirements.txt

pyproject.toml 示例

[project]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

常用命令速查

命令	作用
uv init <name>	创建新项目
uv add <package>	添加依赖
uv add --dev <package>	添加开发依赖
uv remove <package>	移除依赖
uv sync	安装/同步依赖
uv lock	生成 lock 文件
uv lock --upgrade	更新 lock 文件
uv run <command>	在项目环境中运行命令
uvx <tool>	运行工具（无需安装）
uv python install <version>	安装 Python 版本
uv python list	列出可用 Python 版本
uv python pin <version>	锁定项目 Python 版本
uv venv	创建虚拟环境
uv pip install <package>	pip 兼容模式安装
uv pip list	pip 兼容模式列出包
uv pip freeze	pip 兼容模式导出依赖

边界与易混淆点

局限性

• 相对较新：2024-2025 年快速发展，部分边缘场景可能还在完善
• 社区生态：虽然被大量企业采用，但某些私有构建环境可能有兼容性问题
• 学习成本：如果团队已熟悉 Poetry，切换需要适应

不是

• 不是 pip 的简单替代：功能更全面，是统一工具链
• 不是只能管理 Python：可以管理多个 Python 版本
• 不是只有命令行：也有 Python API

最佳实践

1. 新项目直接用 uv：体验极速开发
2. 使用 uvx 运行工具：无需全局安装
3. 利用 Python 版本管理：无需 pyenv
4. CI/CD 中使用：大幅缩短构建时间

适用场景

• ✅ 新项目（强烈推荐）
• ✅ CI/CD 需要极速构建
• ✅ 需要统一管理多个 Python 版本
• ✅ 追求现代、高效的开发体验
• ✅ 替代 pip + venv + pyenv 的组合
• ⚠️ 已有 Poetry 项目的迁移（需要评估）
• ❌ 需要最严格依赖解析的遗留项目（暂时保留 Poetry）

性能对比

依赖安装速度

工具	安装 FastAPI + 依赖	时间
pip	安装 FastAPI + 依赖	~15s
Poetry	安装 FastAPI + 依赖	~20s
uv	安装 FastAPI + 依赖	~1.5s

CI/CD 场景

uv 在 CI/CD 中的优势尤为明显：

• 依赖缓存更智能
• 安装速度提升 10-100 倍
• 减少构建时间和成本

VS Code 集成配置

基础配置

在项目根目录的 .vscode/settings.json 中添加：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

Windows 用户使用：

{
  "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe"
}

与 Pylance 和 Ruff 配合

uv 负责环境管理，VS Code 官方 Python 插件（Pylance）负责代码补全，Ruff 负责格式化和检查。

推荐配置（.vscode/settings.json）：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

插件选择建议

保留的插件：

• VS Code 官方 Python 插件（Microsoft 出品）
• Pylance（智能提示和类型检查）
• Ruff 插件（代码格式化和检查）

可以卸载的插件：

• Poetry 相关插件
• Pipenv 相关插件
• 第三方虚拟环境管理 UI 插件

相关链接

• uv 官方文档
• uv GitHub
• Ruff（同一团队开发的代码检查工具）