跳到主要内容UV Python 包管理工具使用教程（Ubuntu 24.04） | 极客日志PythonAI
UV Python 包管理工具使用教程（Ubuntu 24.04）
介绍在 Ubuntu 24.04 LTS 环境下使用 UV 进行 Python 包管理的完整教程。UV 是 Astral 开发的下一代工具，替代 pip 和 venv，具备极速解析、虚拟环境集成及锁文件支持。内容包括安装验证、初始化项目、依赖管理（add/remove/sync）、虚拟环境操作、缓存清理及工程化实践。通过 uv init 创建项目，uv add 安装依赖，uv run 运行脚本，配合 pyproject.toml 和 uv.lock 实现环境一致性。适合需要高效管理 Python 开发环境及部署的场景，特别兼容大模型依赖如 torch 和 transformers。
女王3 浏览 UV 使用教程（适配 Ubuntu 24.04 LTS）
前言
UV 是由 Astral 公司开发的下一代 Python 包管理工具，旨在替代 pip、venv、pip-tools 等传统工具，核心优势是极致的速度（依赖解析速度比 pip 快 10-100 倍）、一站式功能（集成虚拟环境、依赖解析、锁文件、缓存管理）、原生兼容 Ubuntu 系统，同时完全兼容 Python 生态（支持 、）。它可以很方便地管理一台电脑上不同的 Python 版本，是运行不同环境下程序的好帮手。
pyproject.toml
requirements.txt
前置条件
- 默认电脑已下载 Python 3.XX.X 版本
- 默认操作者有一定基础的 Linux 命令行基础
- 默认操作者的电脑里已有项目
一、安装 UV
1.1 系统兼容性验证
Ubuntu 24.04 LTS 已满足 UV 运行要求（glibc 2.35+），无需额外依赖，直接安装即可。
| 系统 | 支持版本 | 核心依赖 |
|---|
| Linux | Ubuntu 20.04+、CentOS 8+ | glibc 2.28+ |
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: command not found，手动添加环境变量并重启终端：
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
1.4 卸载 UV
如需卸载，执行以下命令（彻底清理安装文件和缓存）：
rm -f ~/.cargo/bin/uv
rm -rf ~/.cache/uv
rm -rf ~/.config/uv
二、核心概念
在使用 UV 前，先理解 4 个核心概念，避免操作误区：
| 概念 | 作用 | 对应文件/目录 |
|---|
| 虚拟环境 | 隔离项目依赖，避免全局 Python 环境污染（Ubuntu 系统 Python 需保留系统依赖） | .venv/（项目根目录，默认隐藏） |
| pyproject.toml | 项目配置文件，定义依赖、Python 版本、项目元信息（替代 requirements.txt） | 项目根目录/pyproject.toml |
| uv.lock | 依赖锁文件，记录所有依赖（含间接依赖）的精确版本（保证多环境一致性） | 项目根目录/uv.lock |
| 缓存 | 存储下载的依赖包、编译后的扩展，避免重复下载/编译（节省时间和带宽） | ~/.cache/uv（用户级缓存目录） |
三、基础操作
3.1 初始化项目
进入你的 Python 项目目录（如 ~/coding/sxu_202501_v2），执行 uv init 完成项目初始化，自动创建虚拟环境和配置文件：
cd ~/coding/sxu_202501_v2
uv init
执行后项目目录结构（Ctrl + H 可查看隐藏目录）
sxu_202501_v2/
├── .venv/ # 自动创建的虚拟环境（隐藏目录，包含独立 Python 解释器）
├── pyproject.toml # 项目配置文件（依赖、Python 版本等）
└── uv.lock # 依赖锁文件（自动生成，不可手动编辑）
自定义初始化参数（新手跳过）
uv init --python 3.12
uv init --no-venv
uv init --name "auto-grading-agent" --author "lemon <[email protected]>"
uv init --python 3.12 --add numpy transformers
3.2 虚拟环境操作
UV 的虚拟环境默认与项目绑定（.venv/），无需手动创建，核心操作如下：
激活虚拟环境
激活后终端前缀会显示 (.venv)，表示已进入隔离环境（所有操作仅对当前项目生效）：
source .venv/bin/activate
验证虚拟环境激活状态
退出虚拟环境
查看虚拟环境信息
uv venv --path
uv pip list
删除虚拟环境
uv venv --remove
rm -rf .venv
3.3 依赖管理
UV 的依赖管理围绕 pyproject.toml 展开，兼容传统 requirements.txt，核心命令是 uv add（安装）、uv remove（卸载）、uv sync（同步）。
安装依赖
安装单个生产依赖（新手跳）
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
uv add git+https://github.com/huggingface/transformers.git@main
安装开发依赖（仅本地开发用，如测试工具，新手跳）
开发依赖不会被打包到生产环境，用 -d/--dev 标记：
uv add pytest -d
uv add black flake8 isort mypy -d
从 requirements.txt 导入依赖（兼容旧项目）
如果你的项目已有 requirements.txt，可直接导入到 pyproject.toml：
uv add -r requirements.txt
uv add -r requirements-dev.txt -d
卸载依赖
uv remove requests
uv remove numpy pandas
uv remove pytest -d
更新依赖
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
uv run python
uv run pytest tests/
uv run black src/
uv run flake8 src/
四、依赖管理深度解析（新手了解即可）
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 = "[email protected]" }
]
dependencies = [
"requests>=2.31.0",
"transformers>=4.41.0",
]
requires-python = ">=3.12"
dev-dependencies = [
"pytest>=7.0.0",
"black>=24.0.0",
]
[tool.uv]
virtualenv = { path = ".venv" }
pip-compatibility = true
手动编辑 pyproject.toml（进阶）
如果需要调整依赖版本约束、添加项目元信息，可直接编辑该文件，修改后执行 uv sync 生效：
[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（如适配旧部署流程），执行以下命令：
uv export > requirements.txt
uv export --dev > requirements-dev.txt
uv export --locked > requirements-locked.txt
uv export --exclude torch > requirements-no-torch.txt
五、缓存精细化管理
UV 的缓存默认存储在 ~/.cache/uv，包含下载的依赖包、编译后的 C 扩展（如 torch 的 CUDA 扩展），是磁盘占用的主要来源，核心操作如下：
5.1 查看缓存信息
5.2 清理缓存
uv cache clean
uv cache prune
uv cache clean transformers
uv cache clean --artifacts
uv cache clean --index
5.3 禁用缓存（不推荐使用）
uv add requests --no-cache
uv sync --no-cache
六、工程化实践（Ubuntu 开发/部署）
6.1 多人协作规范（Git 相关）
- 必须提交到 Git 的文件：
pyproject.toml、uv.lock（保证所有人环境一致）；
- 协作流程：
- 拉取他人代码后，执行
uv sync 自动同步依赖；
- 新增依赖后，执行
uv add <pkg>，提交 pyproject.toml 和 uv.lock；
- 版本冲突时，优先执行
uv lock --force 重新生成锁文件。
必须忽略的文件：添加到 .gitignore，避免提交冗余文件：
cat > .gitignore <<EOF
# UV 相关
.venv/
uv.lock.bak
# 缓存和临时文件
__pycache__/
*.pyc
*.pyo
# 环境变量文件
.env
.env.local
# 大文件
*.pth
*.bin
models/
EOF
6.2 Ubuntu 系统下的 IDE 集成（VSCode/PyCharm）
VSCode 集成
- 打开项目后，VSCode 会自动识别
.venv 虚拟环境；
- 手动指定解释器：
- 按
Ctrl+Shift+P，输入'Python: Select Interpreter'；
- 选择
./.venv/bin/python（项目内的虚拟环境）；
- 安装 Python 插件后，可直接运行/调试脚本（自动使用虚拟环境）。
PyCharm 集成
- 打开项目 →
File → Settings → Project: 项目名 → Python Interpreter；
- 点击齿轮图标 →
Add → Virtualenv Environment；
- 选择
Existing environment，浏览到项目内的 .venv/bin/python → OK。
6.3 离线模式（无网络环境开发）
uv cache add -r requirements.txt
cp -r ~/.cache/uv /media/lemon/U 盘中的缓存目录
export UV_CACHE_DIR="/media/lemon/U 盘中的缓存目录"
uv sync --offline
6.4 部署到 Ubuntu 服务器（无开发依赖）
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
git clone https://github.com/your-username/auto-grading-agent.git
cd auto-grading-agent
uv sync --no-dev
nohup uv run main.py > app.log 2>&1 &
七、故障排查
7.1 常见错误及解决方案
| 错误现象 | 原因分析 | 解决方案 |
|---|
uv: command not found | 环境变量未生效或安装失败 | 1. 重启终端；2. 手动添加环境变量：echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc；3. 重新执行安装脚本 |
| 依赖安装失败（网络超时） | 国外 PyPI 镜像访问缓慢 | 配置国内镜像：uv config set registry https://pypi.tuna.tsinghua.edu.cn/simple |
| 虚拟环境激活失败（权限不足） | .venv/bin/activate 无执行权限 | 赋予权限：chmod +x .venv/bin/activate，再重新激活 |
| 依赖解析冲突（Version solving failed） | 依赖版本约束冲突（如 A 需 B>=2.0，C 需 B<=1.0） | 1. 放宽 pyproject.toml 中的版本约束；2. 执行 uv lock --force 强制解析；3. 更换依赖版本 |
| 编译依赖失败（如 torch、numpy） | 缺少系统编译依赖 | 安装编译工具：sudo apt install build-essential python3-dev libopenblas-dev |
uv run 提示'无权限访问文件' | 目标文件/目录权限不足 | 赋予权限：chmod -R 755 目标目录（如 chmod -R 755 ./data） |
7.2 查看详细日志
uv add transformers --verbose
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
8.2 并行安装与编译优化
uv add numpy pandas transformers --jobs 8
export UV_BUILD_FLAGS="-O3 -march=native"
uv add numpy
8.3 减少缓存占用（长期优化）
uv config set cache.max-size "10GB"
echo 'uv cache prune --older-than 7d' >> ~/.bashrc
九、UV vs 传统工具
| 功能 | UV | pip + venv | Pipenv | Poetry |
|---|
| 依赖解析速度 | 极快（毫秒级） | 慢（秒/分钟级） | 中等 | 中等 |
| 虚拟环境集成 | 内置（自动创建） | 需手动创建（python -m venv） | 内置 | 内置 |
| 锁文件 | 自动生成（uv.lock） | 无 | 自动生成（Pipfile.lock） | 自动生成（poetry.lock） |
| 缓存管理 | 精细化命令（clean/prune） | 基础（pip cache） | 无 | 基础 |
| 开发依赖区分 | 原生支持（-d） | 需手动维护两份 txt | 原生支持 | 原生支持 |
| Ubuntu 兼容性 | 原生适配 | 兼容但繁琐 | 兼容但易出问题 | 兼容但依赖多 |
| 大模型依赖安装（如 torch） | 自动编译优化 | 需手动指定 wheel | 易失败 | 配置复杂 |
9.1 从 pip 迁移到 UV
cd ~/coding/old-project
pip freeze > requirements.txt
uv init --python 3.12 --add -r requirements.txt
uv run main.py
十、常用命令速查表
基础命令
| 命令 | 作用 |
|---|
uv --version | 查看 UV 版本 |
uv init | 初始化项目 + 虚拟环境 |
uv add <pkg> | 安装生产依赖 |
uv add <pkg> -d | 安装开发依赖 |
uv remove <pkg> | 卸载依赖 |
uv run <script> | 运行 Python 脚本（使用项目环境） |
uv sync | 同步依赖到虚拟环境 |
虚拟环境命令
| 命令 | 作用 |
|---|
source .venv/bin/activate | 激活虚拟环境 |
deactivate | 退出虚拟环境 |
uv venv --path | 查看虚拟环境路径 |
uv venv --remove | 删除虚拟环境 |
uv run python --version | 查看虚拟环境 Python 版本 |
缓存命令
| 命令 | 作用 |
|---|
uv cache info | 查看缓存信息（大小、路径） |
uv cache clean | 清理全部缓存 |
uv cache prune | 清理未使用的缓存 |
uv cache clean <pkg> | 清理指定包的缓存 |
高级命令
| 命令 | 作用 |
|---|
uv lock | 生成/更新锁文件 |
uv lock --force | 强制重新生成锁文件 |
uv export | 导出依赖到 requirements.txt |
uv config set <key> <value> | 配置 UV 全局参数（如镜像） |
uv sync --no-dev | 仅同步生产依赖（部署用） |
uv sync --upgrade | 更新所有依赖到最新兼容版本 |
总结
- UV 是 Ubuntu 24.04 LTS 下 Python 开发的最优解，核心优势是速度快、集成度高、操作简洁，完全替代
pip+venv；
- 核心工作流：
uv init（初始化项目）→ uv add（安装依赖）→ uv run（运行代码）→ uv sync（同步环境）→ uv cache clean（清理缓存）；
- 多人协作时，提交
pyproject.toml 和 uv.lock，忽略 .venv，确保所有开发者环境一致。
微信扫一扫，关注极客日志
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
- curl 转代码
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
- Markdown转HTML
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
