UV Python 包管理工具使用教程（Ubuntu 24.04）

二、核心概念

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

三、基础操作

3.1 初始化项目

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

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

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

my_project/
├── .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 "demo-project" --author "Author <[email protected]>"
# 初始化时直接安装依赖（如 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/user/projects/my_project/.venv/bin/python
# 查看当前 pip 路径（应指向.venv/bin/pip）
which pip

退出虚拟环境

deactivate

查看虚拟环境信息

# 查看虚拟环境路径
uv venv --path # 示例输出：/home/user/projects/my_project/.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 = "demo-project"        # 项目名称（初始化时指定）
version = "0.1.0"            # 项目版本
description = "Add your description here" # 项目描述（可手动补充）
authors = [
  { name = "Author", email = "[email protected]" } # 作者信息 (可省略）
]
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/user/.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 相关）

1. 必须提交到 Git 的文件：pyproject.toml、uv.lock（保证所有人环境一致）；
2. 协作流程：
   • 拉取他人代码后，执行 uv sync 自动同步依赖；
   • 新增依赖后，执行 uv add <pkg>，提交 pyproject.toml 和 uv.lock；
   • 版本冲突时，优先执行 uv lock --force 重新生成锁文件。

必须忽略的文件：添加到 .gitignore，避免提交冗余文件：

# 在项目根目录创建 .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 集成

1. 打开项目后，VSCode 会自动识别 .venv 虚拟环境；
2. 手动指定解释器：
   • 按 Ctrl+Shift+P，输入'Python: Select Interpreter'；
   • 选择 ./.venv/bin/python（项目内的虚拟环境）；
3. 安装 Python 插件后，可直接运行/调试脚本（自动使用虚拟环境）。

PyCharm 集成

1. 打开项目 → File → Settings → Project: 项目名 → Python Interpreter；
2. 点击齿轮图标 → Add → Virtualenv Environment；
3. 选择 Existing environment，浏览到项目内的 .venv/bin/python → OK。

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

# 1. 在线环境预下载依赖到缓存
uv cache add -r requirements.txt
# 2. 拷贝缓存目录到离线 Ubuntu 机器（如通过 U 盘）
cp -r ~/.cache/uv /media/user/U 盘中的缓存目录
# 3. 离线机器设置缓存目录并安装依赖
export UV_CACHE_DIR="/media/user/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/demo-project.git
cd demo-project
# 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

十、常用命令速查表

基础命令

虚拟环境命令

缓存命令

高级命令

总结

1. UV 是 Ubuntu 24.04 LTS 下 Python 开发的最优解，核心优势是速度快、集成度高、操作简洁，完全替代 pip+venv；
2. 核心工作流：uv init（初始化项目）→ uv add（安装依赖）→ uv run（运行代码）→ uv sync（同步环境）→ uv cache clean（清理缓存）；
3. 多人协作时，提交 pyproject.toml 和 uv.lock，忽略 .venv，确保所有开发者环境一致。