UV 项目管理指南

UV 操作指南

文章目录

[UV 操作指南](#UV 操作指南)
- [🌎 一. UV 介绍](#🌎 一. UV 介绍)
- [🎀 二. 安装 UV](#🎀 二. 安装 UV)
- [📙 三. 操作指南](#📙 三. 操作指南)
- - [🎯 3.1 命令预览](#🎯 3.1 命令预览)
  - [🐍 3.2 Py版本管理](#🐍 3.2 Py版本管理)
  - [🚀 3.3 **项目管理**](#🚀 3.3 项目管理)
  - [🎩 3.4 虚拟环境](#🎩 3.4 虚拟环境)
  - [📦 3.5 依赖管理](#📦 3.5 依赖管理)
  - [🛠️ 3.6 构建与发布](#🛠️ 3.6 构建与发布)
  - [🧰 3.7 辅助工具](#🧰 3.7 辅助工具)
- [🎓 四. 项目实战](#🎓 四. 项目实战)
- [🏆 五. 最佳实践](#🏆 五. 最佳实践)
- [📚 附1：镜像加速](#📚 附1：镜像加速)

🌎 一. UV 介绍

UV 是一个用 Rust 编写的、速度极快的 Python 包和项目管理器。

核心优势：

⚡️ 速度提升：依赖安装比 pip 快 10-100 倍（基于 Rust 并行处理）
📦 全流程管理：支持项目初始化、依赖管理、虚拟环境、打包发布等完整生命周期
🔄 环境隔离：自动管理虚拟环境，区分 dev/prod 依赖
💾 全局缓存：依赖去重存储，节省磁盘空间
🐍 多版本支持：内置 Python 版本管理，可安装/切换不同 Python 解释器
🖥️ 跨平台兼容：支持 macOS/Linux/Windows，无额外依赖

🎀 二. 安装 UV

1. Linux/macOS

shell 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH=$PATH:$HOME/.local/bin

2. Windows

shell 复制代码

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

3. 验证安装

bash 复制代码

uv --version  # 输出格式：uv x.y.z (如 uv 0.1.30)

更多内容，可查看官方安装文档。

📙 三. 操作指南

🎯 3.1 命令预览

bat 复制代码

$ uv --help
一个极速的 Python 包管理器。

用法: uv [OPTIONS] <COMMAND>

命令：
  auth     管理身份认证
  run      运行命令或脚本
  init     创建新项目 
  add      添加依赖到项目 
  remove   从项目移除依赖 
  version  读取或更新项目版本
  sync     更新项目环境 
  lock     更新项目的锁文件 
  export   将项目的锁文件导出为其他格式 
  tree     展示项目的依赖树 
  format   格式化项目中的 Python 代码 
  tool     运行和安装 Python 包提供的工具命令
  python   管理 Python 版本和安装
  pip      通过 pip 兼容接口管理 Python 包
  venv     创建虚拟环境
  build    将 Python 包构建为源码发行版和 wheel 
  publish  将发行版上传到索引 
  cache    管理 uv 的缓存
  self     管理 uv 可执行文件
  help     显示命令文档

Tip ：所有子命令均支持 --help 查看详细用法，如 uv add --help。

🐍 3.2 Py版本管理

shell 复制代码

# 查看已安装/可安装列表
$ uv python list

# 安装Python
$ uv python install 3.12

# 卸载Python
$ uv python uninstall 3.11

# 设置项目默认版本
$ uv python pin 3.14
Updated `.python-version` from `3.12` -> `3.14`

🚀 3.3 项目管理

shell 复制代码

# 1️⃣ 创建项目（自动生成 pyproject.toml、README、src 目录等）
$ uv init hello_uv              				 		# 默认使用系统默认 python
$ uv init -p 3.12 hello_uv       						# 指定 Python 版本

# 2️⃣ 进入项目目录
$ cd my_project

# 3️⃣ 添加依赖（自动写入 pyproject.toml + 更新 lock）
$ uv add requests                 				 		# 运行时依赖
$ uv add ruff --dev                						# 开发依赖（仅 prod 环境不装）

# 4️⃣ 同步环境（等同于 pip install -r uv.lock）
$ uv sync                         					 	# 安装全部依赖（包括 dev）
$ uv sync --no-dev                 						# 只装运行时依赖（prod 场景）

# 5️⃣ 项目验证
$ uv version											 # 项目版本
$ uv run python -c "import sys; print(sys.prefix)" 		 # 查看虚拟环境

# 6️⃣ 运行代码（自动创建并激活虚拟环境）
$ uv run main.py
$ uv run main.py --only-dev

🎩 3.4 虚拟环境

shell 复制代码

# 创建隔离的虚拟环境（替代python -m venv）
$ uv venv .venv

# 指定Python版本
$ uv venv --python 3.12 .venv

# 在虚拟环境中安装种子包
$ uv venv .venv --seed

小技巧 ：激活虚拟环境后，uv 会自动使用该环境的解释器，无需手动切换。

📦 3.5 依赖管理

核心命令	功能	典型场景
`add`	添加依赖到项目	`uv add pandas`
`remove`	从项目移除依赖	`uv remove requests`
`sync`	同步安装所有依赖（极速替代 `pip install`	`uv sync`
`lock`	生成/更新锁文件（`uv.lock` ）	`uv lock`
`tree`	可视化依赖关系	`uv tree --all`
`pip`	兼容 pip 命令的接口	`uv pip list`

❶ 基础操作

shell 复制代码

# 添加生产依赖（写入 pyproject.toml  的 [project.dependencies]）
$ uv add requests  				# 自动选择最新兼容版本
$ uv add "requests>=2.31.0"     # 指定版本约束

# 添加开发依赖（写入 [project.optional-dependencies.dev]）
$ uv add pytest --dev  			# 仅开发环境使用（测试、格式化等工具）
$ uv add "ruff>=0.1.0" --dev    # 代码检查工具

# 移除依赖（自动清理关联依赖）
$ uv remove requests  			# 生产依赖
$ uv remove pytest --dev  		# 开发依赖（必须加 --dev）

❷ 依赖同步

shell 复制代码

# 根据pyproject.toml和uv.lock安装所有依赖
$ uv sync		   # 首次或变更后执行
$ uv sync --check  # 仅检查冲突不安装

# 仅更新锁文件（不安装，用于CI环境预生成锁文件）
$ uv lock  

# 导出依赖清单（兼容传统 requirements.txt ）
$ uv export > requirements.txt   		   # 生产环境依赖
$ uv export --dev > requirements-dev.txt   # 含开发依赖

❸ 依赖可视化

shell 复制代码

$ uv tree				# 查看依赖树（含子依赖版本）
$ uv tree --no-dev      # 查看生产依赖关系
$ uv tree --only-dev    # 查看开发依赖关系
$ uv tree --package requests # 查看单个包依赖关系

❹ pip包管理

完全可以把uv当作pip加速工具，常用命令如下：

shell 复制代码

$ uv pip --help
Manage Python packages with a pip-compatible interface

Usage: uv.exe pip [OPTIONS] <COMMAND>

Commands:
  compile    将"requirements.in"文件编译为"requirements.txt"或"pylock.toml"文件
  sync       将环境与"requirements.txt"或"pylock.toml"文件同步
  install    将包安装到环境中
  uninstall  从环境中卸载包
  freeze     以依赖清单格式列出环境中已安装的包
  list       以表格格式列出环境中已安装的包
  show       显示一个或多个已安装包的信息
  tree       显示环境的依赖树
  check      验证已安装包是否具有兼容的依

shell 复制代码

# 查看包
$ uv pip list
$ uv pip tree

# 安装包
$ uv pip install requests
$ uv pip install requests==2.31.0

# 导出依赖包
$ uv pip freeze > requirements.txt

# 导入依赖包
$ uv pip install -r requirements.txt

# 卸载包
$ uv pip uninstall requests

🛠️ 3.6 构建与发布

shell 复制代码

# 构建分发包(生成sdist和wheel包)
$ uv build --release

# 将构建好的包上传到 PyPI 等索引（需提前配置 .pypirc）
$ uv publish --repository pypi

🧰 3.7 辅助工具

命令	用途	示例
`uv auth login`	登录到 PyPI、GitHub 等仓库	`uv auth login --registry pypi`
`uv cache clean`	清理 uv 缓存（下载的包、构建产物）	`uv cache clean`
`uv format`	使用内置的 ruff /`black` 进行自动格式化	`uv format .`
`uv tool <Name>`	运行第三方工具（如 `uv tool mypy`）	`uv tool install ruff`
`export`	转换锁文件格式（如导出为 requirements.txt ）

shell 复制代码

# 工具是脱离工程环境独立运行的
$ uv tool install ruff     # 代码检查linter
$ uv tool install black    # 代码formatter
$ uv tool list 			   # 查看工具列表

$ uv tool uninstall ruff   #卸载ruff工具

工具是脱离工程环境独立运行的。

🎓 四. 项目实战

1. 项目初始化

bash 复制代码

$ uv init fastapi-demo
$ cd fastapi-demo

2. 添加依赖

bash 复制代码

$ uv add fastapi
$ uv add uvicorn[standard]

3. 编写代码

python 复制代码

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"msg": "Hello, uv & FastAPI"}

4. 运行项目

bash 复制代码

# 开发模式（自动重载）
uv run -- uvicorn main:app --reload

# 生产模式
uv run -- uvicorn main:app --host 0.0.0.0 --port 8000

5. 项目结构

复制代码

fastapi-demo/
├── pyproject.toml    # 项目配置和依赖
├── uv.lock          # 依赖锁定文件
├── .venv/           # 虚拟环境（自动创建）
├── main.py          # 主程序文件
└── README.md

🏆 五. 最佳实践

版本控制 ：将 pyproject.toml 和 uv.lock 纳入版本控制
环境隔离：每个项目使用独立的虚拟环境
依赖锁定 ：定期运行 uv lock 更新锁定文件
CI/CD 集成 ：使用 uv sync 确保环境一致性
多环境管理：为开发、测试、生产环境分别配置依赖

📚 附1：镜像加速

名称	URL	适用场景
清华源	https://pypi.tuna.tsinghua.edu.cn/simple	学术/开发环境，更新快
阿里云	https://mirrors.aliyun.com/pypi/simple/	企业/生产环境，稳定
中科大	https://pypi.mirrors.ustc.edu.cn/simple	科学计算相关包

通过文件配置（uv 或 pip）

toml 复制代码

# uv 的配置文件（如 uv.toml）
[tool.uv.sources]
name = "tuna"
type = "index"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"

或通过环境变量临时指定：

bash 复制代码

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple