【UV】从入门到实战

前言

UV中文文档： uv 中文文档

随着 AI 应用开发进入工程化阶段，Python 项目越来越复杂。

过去开发一个项目可能只需要：

复制代码

pip install openai

而如今一个完整的 AI Agent 项目往往涉及：

复制代码

FastAPI
LangGraph
OpenAI
Anthropic
Redis
Milvus
PostgreSQL
Celery
MCP Server

此时环境管理成为开发过程中最容易踩坑的环节：

开发环境能跑
测试环境报错
Docker环境缺依赖
CI/CD安装太慢
团队成员版本不一致

为了解决这些问题，越来越多企业开始从：pip + virtualenv→Poetry→uv迁移。

本文将系统介绍 uv 的设计理念、核心能力、常用命令以及在 AI 应用开发中的最佳实践。

一、什么是 uv？

1.1 uv 简介

uv 是由 Astral 公司开发的现代 Python 包管理工具。

官方定位：

复制代码

An extremely fast Python package manager.

即：

一个极快的 Python 包管理器。

uv 使用 Rust 编写，目标是统一替代：

复制代码

pip
virtualenv
pip-tools
pyenv
poetry（部分功能）

让开发者只用一个工具即可完成：

Python版本管理
虚拟环境管理
依赖管理
依赖锁定
项目运行

1.2 为什么 uv 会火？

Python生态长期存在一个问题：开发一个项目可能需要多个工具组合。如：

复制代码

pip
virtualenv
requirements.txt
pip-tools
pyenv

而 Node.js 开发者只需要：

复制代码

npm
pnpm
yarn

一个工具即可。uv的出现就是为了统一这一切。

二、uv 与 Conda 的区别

2.1 两者都能管理环境

很多人第一次接触 uv 时会问：

uv 和 conda 是什么关系？

实际上uv和conda都属于环境管理工具。都能：

创建环境
安装依赖
管理Python版本

2.2 核心区别

对比项	uv	Conda
环境管理	√	√
Python依赖管理	√	√
Python版本管理	√	√
系统库管理	×	√
CUDA管理	×	√
速度	极快	较慢
体积	很小	很大
Docker友好	√	一般
AI应用开发	非常适合	适合
科学计算	一般	强

2.3 如何理解两者定位

uv

更像：

复制代码

Rust版
pip + venv + pyenv

专注于：

复制代码

Python工程开发

例如：

Web开发
FastAPI
Agent开发
MCP开发
RAG系统

Conda

更像：

python 复制代码

Python环境+Linux软件包管理器

不仅管理Python包。还管理：

复制代码

CUDA
ffmpeg
opencv
gcc
sqlite

因此更适合：

复制代码

深度学习训练
科学计算
数据科学

所以对于模型的微调训练项目是非常适合的。

三、为什么企业 AI 应用越来越推荐 uv

3.1 安装速度极快

传统：可能需要几分钟。

复制代码

pip install -r requirements.txt

uv：通常快数倍甚至数十倍。

复制代码

uv sync

原因：

Rust实现
并发下载
全局缓存
更高效依赖解析

3.2 保证环境一致

企业最怕：

复制代码

开发能跑
生产崩溃

根本原因往往是：

复制代码

依赖版本不一致

例如：

复制代码

开发：
langchain 0.3.0

生产：
langchain 0.3.6

行为可能完全不同。

uv 使用：

复制代码

pyproject.toml
uv.lock

锁定依赖。

团队成员执行：

复制代码

uv sync

即可获得完全一致环境。

3.3 Docker 更友好

AI应用几乎都会部署到：

复制代码

Docker
Kubernetes
云服务器

uv在容器环境中的表现非常优秀。

构建速度明显优于：

复制代码

pip
conda

3.4 CI/CD 更快

例如：

复制代码

GitHub Actions
GitLab CI
Jenkins

每天执行几十次构建。

uv缓存机制可以显著减少：

复制代码

依赖下载时间

降低构建成本。

3.5 AI框架依赖冲突更少

现代AI项目常见：

复制代码

LangGraph
LangChain
LlamaIndex
CrewAI
OpenAI SDK
Anthropic SDK

经常出现：

复制代码

pydantic冲突
httpx冲突
protobuf冲突

uv 的依赖解析器比 pip 更快、更稳定。

四、安装 uv

4.1 Linux / macOS

python 复制代码

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

4.2 Windows

PowerShell：

复制代码

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

4.3 验证安装

复制代码

uv --version

输出：

复制代码

uv 0.x.x

说明安装成功。

五、创建第一个 uv 项目

5.1 初始化项目

创建项目【my-agent】

python 复制代码

uv init my-agent

生成：

复制代码

my-agent/
├── pyproject.toml
├── README.md
└── main.py

5.2 进入项目

复制代码

cd my-agent

5.3 创建虚拟环境

复制代码

uv venv

生成：

复制代码

.venv/

5.4 激活环境

Linux/macOS：

复制代码

source .venv/bin/activate

Windows：

复制代码

.venv\Scripts\activate

六、依赖管理

6.1 添加依赖（uv add）

1.单个依赖安装

安装 FastAPI：

复制代码

uv add fastapi

安装 OpenAI：

复制代码

uv add openai

2.多个依赖安装

安装多个：

复制代码

uv add fastapi openai redis

3.指定依赖版本

python 复制代码

uv add 'requests==2.31.0'

4.添加一个 Git 依赖项

python 复制代码

uv add git+https://github.com/psf/requests

5.依赖版本约束

bash 复制代码

uv add -r requirements.txt -c constraints.txt

实际上是在 把 requirements.txt 中的依赖导入到当前 uv 项目中，同时使用 constraints.txt 作为版本约束文件。可以拆开理解。

【-r requirements.txt】等价于：pip install -r requirements.txt

【-c constraints.txt】表示：约束文件（Constraint File）

例如：

requirements.txt
复制代码
fastapi
openai
langchain
constraints.txt
复制代码
pydantic==2.11.5
httpx==0.28.1
执行该命令时就是：
bash 复制代码
安装 requirements.txt 中的包

但是如果涉及：

pydantic
httpx

必须使用 constraints.txt 指定的版本

6.2 删除依赖

复制代码

uv remove redis

6.3 更新依赖

1.更新所有依赖

复制代码

uv lock --upgrade

2.更新指定依赖

--upgrade-package 标志会尝试将指定的包更新到最新的兼容版本，同时保持锁定文件的其余部分不变。

bash 复制代码

uv lock --upgrade-package requests

6.4 同步环境

复制代码

uv sync

作用：

python 复制代码

根据uv.lock同步依赖

团队协作最常用命令之一。

七、Python版本管理

7.1 查看可安装版本

复制代码

uv python list

7.2 安装Python

复制代码

uv python install 3.12

7.3 固定项目版本

复制代码

uv python pin 3.12

生成：

复制代码

.python-version

7.4 查看当前版本

复制代码

uv python find

八、运行项目

8.1 运行脚本

复制代码

uv run main.py

无需激活环境。

8.2 运行模块

复制代码

uv run -m app.main

8.3 临时运行工具

例如：

复制代码

uvx ruff check .

类似：

复制代码

npx

无需安装即可运行。

九、AI项目最佳实践

9.1 推荐目录结构

复制代码

agent-project/
│
├── app/
│   ├── api/
│   ├── agents/
│   ├── services/
│   └── tools/
│
├── tests/
├── pyproject.toml
├── uv.lock
└── .env

9.2 推荐依赖安装

复制代码

uv add fastapi
uv add openai
uv add langgraph
uv add pymilvus
uv add redis
uv add sqlalchemy

9.3 Docker中使用

复制代码

FROM python:3.12

COPY . .

RUN pip install uv

RUN uv sync

CMD ["uv","run","main.py"]

十、uv 常用命令速查表

项目管理

复制代码

uv init
uv init my-project

环境管理

复制代码

uv venv
uv sync

依赖管理

复制代码

uv add fastapi
uv add openai

uv remove openai

uv lock
uv sync

Python管理

复制代码

uv python list

uv python install 3.12

uv python pin 3.12

uv python find

运行程序

复制代码

uv run main.py

uv run -m app.main

临时工具运行

复制代码

uvx ruff check .

uvx black .

uvx pytest

十一、什么时候选择 uv？什么时候选择 Conda？

选择 uv

如果项目属于：

复制代码

FastAPI
AI Agent
MCP Server
RAG
LangGraph
OpenAI
Anthropic
Redis
Milvus
PostgreSQL

选择 Conda

如果项目属于：

复制代码

PyTorch训练
TensorFlow训练
CUDA环境
科学计算
数据分析
Jupyter研究

结语

对于现代 AI 应用开发而言，项目的本质已经越来越接近软件工程，而不是单纯的算法研究。

在这种背景下：

复制代码

Conda 更适合科研场景
uv 更适合工程场景

尤其是 FastAPI、Agent、MCP、RAG、多 Agent 等项目，uv 提供了：

更快的依赖安装速度
更稳定的依赖解析
更好的团队协作体验
更友好的 Docker 和 CI/CD 集成

如果你正在构建企业级 AI 应用，那么从项目创建的第一天开始使用 uv，通常会比后期从 pip 或 Conda 迁移更加省心。