UV 使用教程（适配 Ubuntu 24.04.3 LTS）

UV 使用教程（适配 Ubuntu 24.04.3 LTS）

前言

UV 是由 Astral 公司开发的下一代Python包管理工具，旨在替代 pip、venv、pip-tools 等传统工具，核心优势是极致的速度（依赖解析速度比pip快10-100倍）、一站式功能（集成虚拟环境、依赖解析、锁文件、缓存管理）、原生兼容Ubuntu系统，同时完全兼容Python生态（支持pyproject.toml、requirements.txt）。它可以很方便的管理一台电脑上不他同的python版本，是运行不同环境下程序的好帮手

前置条件

默认电脑已经下载python 3.XX.X版本
默认操作者有一定基础的Linux命令行的基础
默认操作者的电脑里以有项目

一、安装 UV

1.1 系统兼容性验证

Ubuntu 24.04.3 LTS 已满足 UV 运行要求（glibc 2.35+），无需额外依赖，直接安装即可。

1.2 一键安装（推荐）

打开终端，执行官方安装脚本（自动适配x86_64架构，无sudo权限也可安装）：

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

安装原理说明

• 脚本会自动下载适配 Ubuntu 24.04 的 UV 二进制文件；
• 默认安装到 ~/.cargo/bin/（依赖 Rust 的 cargo 环境，脚本会自动处理）；
• 自动将 ~/.cargo/bin/ 加入用户环境变量 PATH。

1.3 验证安装

安装完成后，重启终端（使环境变量生效），执行以下命令验证：

uv –version
# 示例输出：uv 0.4.14 (a1b2c3d 2026-01-01) # 版本号可能更新

若提示 uv: command not found，手动添加环境变量并重启终端：

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

1.4 卸载 UV

如需卸载，执行以下命令（彻底清理安装文件和缓存）：

# 删除UV二进制文件
rm -f ~/.cargo/bin/uv
# 清理UV缓存（可选，释放磁盘空间）
rm -rf ~/.cache/uv
# 清理UV配置文件（可选）
rm -rf ~/.config/uv

二、核心概念

在使用UV前，先理解4个核心概念，避免操作误区：

三、基础操作

3.1 初始化项目

进入你的 Python 项目目录（如~/coding/sxu_202501_v2），执行uv init完成项目初始化，自动创建虚拟环境和配置文件：

# 进入项目目录（替换为你的实际项目路径）
cd ~/coding/sxu_202501_v2
# 初始化项目（默认创建虚拟环境+pyproject.toml+uv.lock）
uv init

执行后项目目录结构（ Ctrl + H 可查看隐藏目录）

sxu_202501_v2/
├── .venv/ # 自动创建的虚拟环境（隐藏目录，包含独立Python解释器）
├── pyproject.toml # 项目配置文件（依赖、Python版本等）
└── uv.lock # 依赖锁文件（自动生成，不可手动编辑）

自定义初始化参数（新手跳过）

# 指定Python版本（Ubuntu 24.04默认Python 3.12，可指定其他已安装版本）
uv init –python 3.12
# 不自动创建虚拟环境（仅生成配置文件，适合手动管理环境）
uv init –no-venv
# 指定项目名称和作者（会写入pyproject.toml）
uv init –name "auto-grading-agent" –author "lemon <lemon@example.com>"
# 初始化时直接安装依赖（如numpy、transformers）
uv init –python 3.12 –add numpy transformers

3.2 虚拟环境操作

UV 的虚拟环境默认与项目绑定（.venv/），无需手动创建，核心操作如下：

激活虚拟环境

激活后终端前缀会显示(.venv)，表示已进入隔离环境（所有操作仅对当前项目生效）：

source .venv/bin/activate

验证虚拟环境激活状态

# 查看当前Python解释器路径（应指向.venv/bin/python）
which python
# 示例输出：/home/lemon/coding/sxu_202501_v2/.venv/bin/python

# 查看当前pip路径（应指向.venv/bin/pip）
which pip

退出虚拟环境

deactivate

查看虚拟环境信息

# 查看虚拟环境路径
uv venv –path
# 示例输出：/home/lemon/coding/sxu_202501_v2/.venv

# 查看虚拟环境中已安装的依赖
uv pip list

删除虚拟环境

# 方法1：UV内置命令（推荐，安全清理）
uv venv –remove
# 方法2：手动删除（等价于内置命令）
rm -rf .venv

3.3 依赖管理

UV 的依赖管理围绕pyproject.toml展开，兼容传统requirements.txt，核心命令是uv add（安装）、uv remove（卸载）、uv sync（同步）。

安装依赖

安装单个生产依赖（新手跳）

# 安装最新稳定版（如requests、transformers）
uv add requests
uv add transformers

# 安装指定版本（避免版本兼容问题）
uv add requests==2.31.0
uv add transformers==4.41.0

# 安装版本范围（允许自动更新小版本）
uv add requests>=2.28.0,<3.0.0
uv add torch>=2.0.0,<2.5.0

# 安装Git仓库中的依赖（如自定义分支的包）
uv add git+https://github.com/huggingface/transformers.git@main

安装开发依赖（仅本地开发用，如测试工具，新手跳）

开发依赖不会被打包到生产环境，用-d/–dev标记：

# 安装单个开发依赖（如pytest用于测试）
uv add pytest -d

# 安装多个开发依赖（代码格式化、lint等）
uv add black flake8 isort mypy -d

从requirements.txt导入依赖（兼容旧项目）

如果你的项目已有requirements.txt，可直接导入到pyproject.toml：

# 导入生产依赖
uv add -r requirements.txt

# 导入开发依赖（需单独创建requirements-dev.txt，新手跳）
uv add -r requirements-dev.txt -d

卸载依赖

# 卸载单个生产依赖
uv remove requests

# 卸载多个生产依赖
uv remove numpy pandas

# 卸载开发依赖
uv remove pytest -d

更新依赖

# 更新单个依赖到最新版（按pyproject.toml的版本约束）
uv add requests@latest

# 更新所有生产依赖到最新兼容版本
uv sync –upgrade

# 更新所有依赖（包括开发依赖）到最新兼容版本
uv sync –upgrade –dev

# 强制更新所有依赖到最新版（忽略版本约束，可能导致兼容问题，不建议使用）
uv sync –upgrade-all

同步依赖

当pyproject.toml或uv.lock变更（如拉取他人代码、更新依赖），执行uv sync同步本地环境：

# 同步生产依赖+开发依赖（本地开发用）
uv sync

# 仅同步生产依赖（部署到服务器时用）
uv sync –no-dev

# 同步时强制重新安装所有依赖（修复环境异常）
uv sync –force

3.4 运行Python脚本/命令

UV 提供uv run命令，无需手动激活虚拟环境，直接使用项目环境运行代码（避免误操作全局环境）：

# 运行你的项目脚本
uv run main.py

# 运行带参数的脚本（如传入配置文件、数据路径）
uv run main.py –config config.yaml –data ./data

# 运行Python交互环境（使用项目虚拟环境的Python）
uv run python

# 运行开发工具（如pytest测试、black格式化）
uv run pytest tests/ # 执行测试用例
uv run black src/ # 格式化代码
uv run flake8 src/ # 代码lint检查

四、依赖管理深度解析（新手了解即可）

4.1 pyproject.toml 详解

pyproject.toml是PEP 621标准的项目配置文件，UV生成的默认内容如下（带详细注释）：

[project]
name = "auto-grading-agent" # 项目名称（初始化时指定）
version = "0.1.0" # 项目版本
description = "Add your description here" # 项目描述（可手动补充）
authors = [
{ name = "lemon", email = "lemon@example.com" } # 作者信息(可省略）
]
dependencies = [ # 生产依赖（uv add添加的包自动写入）
"requests>=2.31.0",
"transformers>=4.41.0",
]
requires-python = ">=3.12" # Python版本约束（Ubuntu 24.04默认3.12）
dev-dependencies = [ # 开发依赖（uv add -d添加的包自动写入）
"pytest>=7.0.0",
"black>=24.0.0",
]

[tool.uv]
# UV专属配置（优化Ubuntu环境下的使用体验）
virtualenv = { path = ".venv" } # 虚拟环境路径（固定为项目内.venv）
pip-compatibility = true # 兼容pip的依赖解析逻辑（避免兼容问题）

手动编辑 pyproject.toml（进阶）

如果需要调整依赖版本约束、添加项目元信息，可直接编辑该文件，修改后执行uv sync生效：

# 示例：添加LLM相关依赖
[project]
dependencies = [
"requests>=2.31.0",
"transformers>=4.41.0",
"torch>=2.0.0",
"accelerate>=0.30.0",
"peft>=0.10.0",
]

4.2 锁文件（uv.lock）详解

• 作用：记录所有依赖（包括间接依赖，如transformers依赖的huggingface-hub）的精确版本、下载来源、哈希值，确保在任何Ubuntu环境中安装的依赖完全一致；
• 生成时机：uv init、uv add、uv lock 会自动生成/更新；
• 手动更新锁文件：当修改pyproject.toml后，执行uv lock更新锁文件；
• 强制重新生成锁文件：uv lock –force（忽略缓存，重新解析所有依赖，解决锁文件冲突）；
• Git提交要求：多人协作时，需将uv.lock提交到Git仓库，避免环境不一致。

4.3 依赖导出（兼容传统工具）

如需将UV管理的依赖导出为requirements.txt（如适配旧部署流程），执行以下命令：

# 导出生产依赖到requirements.txt（含版本范围）
uv export > requirements.txt

# 导出开发依赖到requirements-dev.txt
uv export –dev > requirements-dev.txt

# 导出锁文件中的精确版本（无版本范围，保证完全一致）
uv export –locked > requirements-locked.txt

# 导出时排除指定依赖（如无需导出torch）
uv export –exclude torch > requirements-no-torch.txt

五、缓存精细化管理

UV 的缓存默认存储在~/.cache/uv，包含下载的依赖包、编译后的C扩展（如torch的CUDA扩展），是磁盘占用的主要来源，核心操作如下：

5.1 查看缓存信息

uv cache info
# 示例输出：
# Cache directory: /home/lemon/.cache/uv
# Total size: 3.2 GB
# – Downloads: 2.5 GB (原始依赖包下载缓存)
# – Artifacts: 0.6 GB (编译后的扩展，如CUDA相关)
# – Virtualenvs: 0.1 GB (虚拟环境缓存)

5.2 清理缓存

# 清理全部缓存（最常用，安全无副作用）
uv cache clean
# 清理后提示：Deleted 3.2 GB of cache

# 仅清理未使用的依赖缓存（保留当前项目用到的，避免重复下载）
uv cache prune

# 仅清理指定包的缓存（如清理transformers的旧版本缓存）
uv cache clean transformers

# 仅清理编译后的扩展缓存（如CUDA版本切换后）
uv cache clean –artifacts

# 清理缓存并强制刷新索引
uv cache clean –index

5.3 禁用缓存（不推荐使用）

# 安装依赖时不使用缓存（强制重新下载）
uv add requests –no-cache

# 同步依赖时不使用缓存
uv sync –no-cache

六、工程化实践（Ubuntu开发/部署）

6.1 多人协作规范（Git相关）

6.2 Ubuntu系统下的IDE集成（VSCode/PyCharm）

VSCode 集成

PyCharm 集成

6.3 离线模式（无网络环境开发）

# 1. 在线环境预下载依赖到缓存
uv cache add -r requirements.txt

# 2. 拷贝缓存目录到离线Ubuntu机器（如通过U盘）
cp -r ~/.cache/uv /media/lemon/U盘中的缓存目录

# 3. 离线机器设置缓存目录并安装依赖
export UV_CACHE_DIR="/media/lemon/U盘中的缓存目录"
uv sync –offline

6.4 部署到Ubuntu服务器（无开发依赖）

# 1. 服务器安装UV（同本地安装命令）
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# 2. 拉取项目代码
git clone https://github.com/your-username/auto-grading-agent.git
cd auto-grading-agent

# 3. 同步生产依赖（忽略开发依赖）
uv sync –no-dev

# 4. 运行项目（后台运行，适合长期部署）
nohup uv run main.py > app.log 2>&1 &

七、故障排查

7.1 常见错误及解决方案

7.2 查看详细日志

# 运行命令时输出详细日志（如安装依赖失败）
uv add transformers –verbose

# 查看UV的日志文件（Ubuntu下的日志路径）
cat ~/.cache/uv/logs/uv.log

# 导出日志到文件（方便调试）
uv add torch –verbose 2>&1 > uv-install-log.txt

八、性能优化

8.1 加速依赖安装

配置国内PyPI镜像（清华源），解决国外镜像访问慢的问题：

# 永久设置清华源（全局生效）
uv config set registry https://pypi.tuna.tsinghua.edu.cn/simple

# 验证配置是否生效
uv config get registry
# 输出：https://pypi.tuna.tsinghua.edu.cn/simple

8.2 并行安装与编译优化

# 并行安装依赖（指定8个并发任务，Ubuntu 24.04支持多线程）
uv add numpy pandas transformers –jobs 8

# 编译依赖时启用优化（针对CPU架构优化，提升运行速度）
export UV_BUILD_FLAGS="-O3 -march=native"
uv add numpy # 编译时应用优化 flags

8.3 减少缓存占用（长期优化）

# 设置缓存最大大小（如限制为10GB）
uv config set cache.max-size "10GB"

# 自动清理7天前的未使用缓存（定期执行）
echo 'uv cache prune –older-than 7d' >> ~/.bashrc # 每次终端启动时执行

九、UV vs 传统工具

9.1 从pip迁移到UV

# 1. 进入原pip管理的项目目录
cd ~/coding/old-project

# 2. 导出pip依赖到requirements.txt
pip freeze > requirements.txt

# 3. 用UV初始化项目（自动创建虚拟环境）
uv init –python 3.12 –add -r requirements.txt

# 4. 验证迁移成功（运行项目）
uv run main.py

十、常用命令速查表

基础命令

虚拟环境命令

缓存命令

高级命令

总结