项目结构与文件

pyproject.toml

Python 项目元数据定义在 pyproject.toml 文件中。uv 需要此文件来识别项目的根目录。

提示

可以使用 uv init 创建新项目。详情请参阅 创建项目。

最小化的项目定义包含名称和版本

pyproject.toml

[project]
name = "example"
version = "0.1.0"

其他的项目元数据和配置包括

• Python 版本要求
• 依赖项
• 构建系统
• 入口点（命令）

项目环境

在使用 uv 处理项目时，uv 会根据需要创建虚拟环境。虽然某些 uv 命令会创建临时环境（例如 uv run --isolated），但 uv 也会在 pyproject.toml 旁边的 .venv 目录中为项目及其依赖项维护一个持久化环境。它存储在项目内部以便编辑器能够轻松找到——编辑器需要该环境来提供代码补全和类型提示。不建议将 .venv 目录纳入版本控制；它会自动通过内部的 .gitignore 文件从 git 中排除。

要使用项目环境运行命令，请使用 uv run。此外，也可以像普通虚拟环境一样激活项目环境。

当调用 uv run 时，如果项目环境不存在，它将创建该环境；如果已存在，它将确保其为最新状态。也可以使用 uv sync 显式创建项目环境。详情请参阅 锁定与同步 文档。

不建议手动修改项目环境（例如使用 uv pip install）。对于项目依赖项，请使用 uv add 将包添加到环境中。对于一次性需求，请使用 uvx 或 uv run --with。

提示

如果您不希望 uv 管理项目环境，请设置 managed = false 以禁用项目的自动锁定和同步。例如

pyproject.toml

[tool.uv]
managed = false

锁文件 (lockfile)

uv 会在 pyproject.toml 旁边创建一个 uv.lock 文件。

uv.lock 是一个通用或跨平台的锁文件，它捕获了在所有可能的 Python 标记（如操作系统、架构和 Python 版本）下需要安装的包。

与用于指定项目广泛需求的 pyproject.toml 不同，锁文件包含安装在项目环境中的精确解析版本。此文件应纳入版本控制，以便在不同机器上实现一致且可重复的安装。

锁文件确保了参与项目的开发人员使用一致的包版本集合。此外，它还确保在将项目作为应用程序部署时，能够明确所使用的确切包版本。

在调用使用项目环境的 uv 命令（即 uv sync 和 uv run）时，锁文件会自动创建和更新。也可以使用 uv lock 显式更新锁文件。

uv.lock 是一个人类可读的 TOML 文件，但由 uv 管理，不应手动编辑。uv.lock 格式是 uv 特有的，不能被其他工具使用。

与 pylock.toml 的关系

在 PEP 751 中，Python 标准化了一种新的解析文件格式：pylock.toml。

pylock.toml 是一种旨在取代 requirements.txt 的解析输出格式（例如，在 uv pip compile 的上下文中，通过一组输入需求生成一个“已锁定”的 requirements.txt 文件）。pylock.toml 是标准化的且与工具无关，因此在未来，由 uv 生成的 pylock.toml 文件可以被其他工具安装，反之亦然。

uv 的某些功能无法在 pylock.toml 格式中表达；因此，uv 将在项目接口内继续使用 uv.lock 格式。

不过，uv 支持将 pylock.toml 作为导出目标，并支持在 uv pip 命令行界面中使用它。例如

• 要将 uv.lock 导出为 pylock.toml 格式，请运行：uv export -o pylock.toml
• 要根据一组需求生成 pylock.toml 文件，请运行：uv pip compile requirements.in -o pylock.toml
• 要从 pylock.toml 文件安装，请运行：uv pip sync pylock.toml 或 uv pip install -r pylock.toml