当前位置：首页 > news >正文

【知识】UV Python 快速入门指南

news 2025/8/16 11:27:23

以下是一份针对初次使用 UV 的 Python 程序员的详细文档。内容涵盖核心概念、安装配置、常用命令详解、从零到一的项目实战示例，以及与其他常见工具的对比和进阶技巧，帮助你顺畅掌握 UV。

一、什么是 UV？

UV 是一个基于 Rust 的 Python 依赖管理与环境工具，它将常见的 pip、venv、pyenv 等功能整合到一个统一的命令行界面中。相比传统工具，UV 的优势在于：

更快的依赖解析和安装速度（Rust 实现，性能提升约 10 倍）
原生支持多 Python 版本切换
内置项目初始化和打包功能，减少手动配置
统一的依赖树展示和版本锁定机制

二、安装与初始配置

系统要求
- Python 3.7 及以上
- Rust 虚拟环境（可选，UV 自带预编译二进制）

全局安装 UV

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# 或者使用 pip（会略慢）
pip install uv#如果你支持pipx，也可以安装到隔离环境中
pipx install uv

验证安装
```
uv --version
```

三、管理 Python 版本

UV 支持列出、安装和切换多个 Python 解释器：

列出本机可用版本

bash
```
uv python list
```
安装指定 CPython 版本（示例：3.12）

bash
```
uv python install cpython3.12
```
在某个命令中使用指定版本

bash
```
uv run -p 3.12 xxx.py
```
进入交互式界面

bash
```
uv run -p 3.12 python
```
使用系统默认或当前环境

bash
```
uv run xxx.py
```

四、核心命令详解

下表总结了 UV 最常用的命令及作用：

命令	作用说明	示例
uv init	在当前目录创建 UV 项目（生成配置文件、虚拟环境结构等）	`uv init`
uv add <package>	向项目添加依赖，并自动更新锁文件	`uv add pydantic`
uv remove <package>	从项目中移除依赖	`uv remove pydantic`
uv tree	打印当前项目的依赖树	`uv tree --depth 2`
uv build	构建项目，生成可分发包或二进制文件	`uv build`
uv lock	（进阶）仅更新锁文件，不实际安装	`uv lock --check`
uv clean	（进阶）清理缓存与无用文件	`uv clean`

五、从零到一：第一个 UV 项目

初始化项目

bash
```
mkdir my_uv_project && cd my_uv_project
uv init
```
- 在当前目录生成 uv.toml（或 pyproject.toml）和 .venv。
添加依赖

bash
```
uv add requests fastapi
```
- uv tree 可查看依赖关系。

编写示例脚本 app.py

python

from fastapi import FastAPI
import requestsapp = FastAPI()@app.get("/")
async def root():resp = requests.get("https://api.github.com")return {"status_code": resp.status_code}

运行脚本

bash
```
uv run app.py
```

构建分发包

bash

uv build
# 生成 dist/ 目录下的 wheel 或可执行文件

六、与 Pip、Poetry、Conda 的对比

特性	UV	Pip + venv	Poetry	Conda
依赖解析速度	极速（Rust 实现）	中等	中等	较慢
多 Python 版本管理	内置支持	需手动配置 pyenv	需配合 pyenv 或 plugin	内置支持
项目初始化	一条命令完成	手动 `venv` + `pip`	`poetry init`	手动 `conda create`
构建/打包	内置 `uv build`	setuptools/Cython 等	内置 `poetry build`	需额外工具
社区成熟度	新兴	广泛	成熟	成熟

七、进阶技巧与常见问题

切换已有项目的全局环境：

bash
```
uv env use /path/to/python3.11
```
锁文件失效或依赖冲突时，强制更新锁文件：

bash
```
uv lock --force
```

在 CI/CD 中使用：

yaml

steps:- name: Checkoutuses: actions/checkout@v2- name: Install UVrun: curl -sSf https://uv.dev/install.sh | bash- name: Install Dependenciesrun: uv install- name: Run Testsrun: uv run pytest