使用 uv 更新 requirements.txt 文件

问题描述

当使用 uv 管理 Python 项目依赖时，本地会生成 uv.lock 文件锁定依赖版本，而生产环境通常需要标准的 requirements.txt 文件。用户在升级依赖后：

1. 通过 uv lock --upgrade 更新了锁文件（例如将 dj-database-url 从 2.2.0 升级到 2.3.0）
2. 尝试用 uv pip compile pyproject.toml --output-file requirements.txt 生成新 requirements.txt
3. 生成的 requirements.txt 仍显示旧版本，未包含更新后的包

核心问题：如何正确将 uv.lock 中的更新同步到 requirements.txt？

解决方案

使用 uv export 命令直接从锁文件（lockfile）导出兼容 pip 的 requirements.txt 格式。这是最可靠的方法，无需依赖本地环境状态。

基础命令

# 导出带哈希值的 requirements.txt（推荐生产环境使用）
uv export --format requirements.txt > requirements.txt

# 或省略哈希值（简化文件）
uv export --format requirements.txt --no-hashes > requirements.txt

验证结果

执行后检查 requirements.txt，确认包版本已更新（如 dj-database-url==2.3.0）。

完整工作流

具体步骤：

1. 升级依赖（如 pyproject.toml 有改动）：

   uv lock --upgrade

2. 导出 requirements.txt：

   # 推荐：导出并排除开发依赖
   uv export --no-dev --format requirements.txt --no-hashes > requirements.txt

关键选项说明

选项	作用	使用场景
--no-dev	排除开发依赖（如 pytest, mypy）	生产环境部署
--no-hashes	省略包的哈希校验值	简化文件，加速安装
--no-header	移除文件头部注释	减少冗余信息
--output-file <路径>	直接输出到文件（替代 > 重定向）	避免终端输出干扰

备选方案：uv pip freeze

若需基于当前虚拟环境生成依赖列表（而非 lockfile 文件），可用：

uv pip freeze > requirements.txt

注意

uv pip freeze 依赖于当前激活环境的包状态。若未在虚拟环境中操作，可能包含无关依赖。
推荐优先使用基于 lockfile 的 uv export 以保证一致性。

常见问题

为什么不推荐 uv pip compile?

原问题中的 uv pip compile pyproject.toml 用于生成 lockfile（如 uv.lock），并非直接导出 requirements.txt 格式。直接使用 uv export 能正确转换 lockfile 内容。

如何控制开发依赖？

通过 --no-dev 排除仅用于开发的包：

# 生产环境用（不含 dev 依赖）
uv export --no-dev --format requirements.txt > requirements_prod.txt

# 开发环境用（包含全部依赖）
uv export --with-dev --format requirements.txt > requirements_dev.txt

总结

正确工作流：

1. 更新 pyproject.toml 后运行 uv lock --upgrade 同步锁文件
2. 执行 uv export --format requirements.txt --no-hashes --no-dev > requirements.txt
3. 将生成的 requirements.txt 部署到生产环境

此方法确保依赖版本与 lockfile 严格一致，且格式兼容 pip install -r requirements.txt。