项目结构和文件

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

锁定文件

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 CLI 中。例如

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