UV 包管理工具在 Ubuntu 24.04 下的实战指南

基础操作

初始化项目

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

cd ~/projects/my_project
uv init

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

my_project/
├── .venv/          # 自动创建的虚拟环境
├── pyproject.toml  # 项目配置文件
└── uv.lock         # 依赖锁文件

自定义初始化参数（进阶选项）：

# 指定 Python 版本
uv init --python 3.12
# 不自动创建虚拟环境
uv init --no-venv
# 指定项目名称和作者
uv init --name "auto-grading-agent" --author "[email protected]"
# 初始化时直接安装依赖
uv init --python 3.12 --add numpy transformers

虚拟环境操作

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

激活虚拟环境： 激活后终端前缀会显示 (.venv)，表示已进入隔离环境。

source .venv/bin/activate

验证状态：

which python
# 应指向 .venv/bin/python
which pip

退出与删除：

deactivate
uv venv --remove
# 或手动删除
rm -rf .venv

依赖管理

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

安装依赖：

# 安装生产依赖
uv add requests
uv add transformers

# 安装指定版本
uv add requests==2.31.0

# 安装 Git 仓库中的依赖
uv add git+https://github.com/huggingface/transformers.git@main

# 安装开发依赖（仅本地用）
uv add pytest -d

从 requirements.txt 导入：

uv add -r requirements.txt

更新与同步：

# 更新单个依赖
uv add requests@latest

# 同步所有依赖
uv sync

# 仅同步生产依赖（部署用）
uv sync --no-dev

运行脚本

UV 提供 uv run 命令，无需手动激活虚拟环境，直接使用项目环境运行代码：

uv run main.py
uv run pytest tests/

深度解析

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

修改后需执行 uv sync 生效。

锁文件（uv.lock）

• 作用：记录所有依赖的精确版本、来源、哈希值，确保环境一致性。
• 生成时机：uv init、uv add、uv lock 自动生成。
• Git 协作：多人协作时，必须提交 uv.lock 到仓库。

依赖导出

如需导出为 requirements.txt：

uv export > requirements.txt
uv export --locked > requirements-locked.txt

缓存管理

UV 的缓存默认存储在 ~/.cache/uv，包含下载的依赖包和编译后的 C 扩展。

查看信息：

uv cache info

清理缓存：

uv cache clean
uv cache prune

禁用缓存（慎用）：

uv add requests --no-cache

工程化实践

多人协作规范

1. 必须提交：pyproject.toml、uv.lock。
2. 必须忽略：添加到 .gitignore。

# .gitignore
.venv/
uv.lock.bak
__pycache__/
*.pyc
.env

IDE 集成

VSCode： 打开项目后自动识别 .venv，通过 Python: Select Interpreter 选择 ./.venv/bin/python。

PyCharm： 设置 → Project → Python Interpreter → Add → Existing environment → 选择 .venv/bin/python。

离线模式

# 在线预下载
uv cache add -r requirements.txt
# 拷贝缓存到离线机器
export UV_CACHE_DIR="/path/to/cache"
uv sync --offline

服务器部署

# 安装 UV
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# 同步生产依赖
uv sync --no-dev

# 后台运行
nohup uv run main.py > app.log 2>&1 &

故障排查

性能优化

加速安装： 配置国内 PyPI 镜像（清华源）。

uv config set registry https://pypi.tuna.tsinghua.edu.cn/simple

并行安装：

uv add numpy pandas --jobs 8

限制缓存大小：

uv config set cache.max-size "10GB"

常用命令速查

总结

UV 是 Ubuntu 24.04 下 Python 开发的最优解之一，核心优势是速度快、集成度高。核心工作流为：uv init → uv add → uv run → uv sync。多人协作时，务必提交 pyproject.toml 和 uv.lock，忽略 .venv，以确保环境一致。