[Python] Python配置uv环境

好的，我将参照您提供的 fzf 教程结构，为您修订关于 uv 依赖管理工具的内容。

---

目录

• 01 背景
  • 1.1 简介
  • 1.2 官网
• 02 安装
  • 2.1 下载与安装
  • 2.2 验证
• 03 项目与环境管理
  • 3.0 下载指定版本Python
  • 3.1 创建项目（初始化）
  • 3.2 激活与运行
  • 3.3 传统激活方法（用于交互式会话）
• 04 依赖包管理
  • 4.1 安装新包
  • 4.2 兼容 pip install
  • 4.3 同步与安装所有依赖
  • 4.4 查看已安装的包
  • 4.5 常用包示例
• 05 运行代码 (总结)

01 背景

1.1 简介

uv 是由 Astral 公司（也开发了 Ruff）推出的下一代 Python 打包和依赖管理工具。它被设计为一个极快的 pip 和 pip-tools 替代品，核心功能是包安装、依赖解析和虚拟环境管理。

主要特点：

• 速度极致： uv 的核心是用 Rust 编写的，其依赖解析器和安装器比传统的 CPython 工具快 10 到 100 倍。
• 一体化： 旨在替代 pip、pip-compile 和 virtualenv 的功能，简化 Python 依赖管理流程。
• 与现有生态兼容： 支持标准的 pyproject.toml 和 requirements.txt 文件，易于集成到现有项目中。
• 推荐工作流： 鼓励使用 uv run 直接执行脚本，避免频繁手动激活和退出虚拟环境。

1.2 官网

uv 的Github地址为：GitHub: astral-sh/uv
uv 的中文文档地址为: uv 中文文档

02 安装

2.1 下载与安装

注意：出于安全和隔离考虑，uv 不建议在 root 用户下安装，请使用普通用户进行安装。

# 使用 curl 下载并执行官方安装脚本
# -L：跟随重定向
# -sS：静默模式，但显示错误信息
# -f：如果下载失败则命令失败
curl -LsSf https://astral.sh/uv/install.sh | sh

安装脚本会自动将 uv 二进制文件放置到 $HOME/.cargo/bin 目录下，并提示你更新 $PATH 环境变量。

2.2 验证

安装完成后，验证 uv 是否可用：

uv --version

03 项目与环境管理

3.0 下载指定版本Python

# 同时下载3.11和3.12版本的Python
uv python install 3.11 3.12

3.1 创建项目（初始化）

uv init 命令不仅初始化项目，还会自动创建并配置一个虚拟环境 (.venv 目录)，并创建标准的 pyproject.toml 和 uv.lock 文件。

# 指定虚拟环境python版本为 3.11
uv venv --python 3.11
uv venv activate

# 创建并进入项目目录
uv init Project_test
cd Project_test

项目结构要点：

文件/目录	描述
.venv/	自动创建的 Python 虚拟环境目录。
pyproject.toml	配置文件，用于声明项目依赖。
uv.lock	锁定文件，记录所有依赖的精确版本，确保环境可复现。

3.2 激活与运行

uv 强烈推荐使用 uv run 命令直接在虚拟环境中执行脚本，而不推荐手动激活环境。

用途	命令示例	描述
执行 Python 代码	uv run python main.py	直接在 .venv 环境中运行 main.py。
执行测试	uv run pytest	在环境中查找并运行 pytest 命令。
代码格式化	uv run black .	在环境中查找并运行 black 工具。

3.3 传统激活方法（用于交互式会话）

如果需要进行多次交互式操作或调试，仍然可以使用传统方式激活虚拟环境：

# 激活虚拟环境
source .venv/bin/activate

# ..... 可以在此执行多次 pip install/list/run 操作 .....

# 退出虚拟环境
deactivate

04 依赖包管理

uv 提供了比 pip 更快、更统一的依赖管理接口。

4.1 安装新包

uv add 命令用于安装依赖包，并会自动更新 pyproject.toml 和 uv.lock 文件。

场景	命令示例
安装单个包	uv add requests
安装多个包	uv add pandas numpy matplotlib
安装特定版本	uv add "django==4.2.0"
安装开发依赖	uv add --dev pytest black

4.2 兼容 pip install

uv 通过 uv pip install 命令提供了与传统 pip 兼容的安装接口，同样速度极快。

# 使用类似 pip 的语法安装包
uv pip install requests
uv pip install -r requirements.txt

4.3 同步与安装所有依赖

uv sync 命令会读取 uv.lock 或 pyproject.toml 中的依赖列表，确保 .venv 环境中的包与列表完全同步（相当于 pip install -r requirements.txt 的极速版）。

# 安装或更新项目所有依赖，保持环境与 lock 文件一致
uv sync

4.4 查看已安装的包

由于 uv 默认没有 uv list 命令，需要通过 uv run 来执行环境中的 pip 命令：

uv run pip list

4.5 常用包示例

领域	包名	命令示例
数据分析	pandas, numpy, matplotlib, seaborn	uv add pandas numpy matplotlib
Web 开发	fastapi, uvicorn, sqlalchemy	uv add fastapi uvicorn
开发工具 (dev-dependencies)	pytest, black, flake8, mypy	uv add --dev pytest black flake8

05 运行代码 (总结)

场景	命令	描述
执行 Python 脚本	uv run python script.py	推荐的单次执行方式。
运行测试套件	uv run pytest	推荐的测试方式。
格式化代码	uv run black .	推荐的代码格式化方式。
检查代码质量	uv run flake8	推荐的代码质量检查方式。
交互式工作流	source .venv/bin/activate	用于需要多次操作或调试的会话。