项目结构和文件

`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 目录纳入版本控制，uv 会通过内部的 .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 命令行界面中支持。例如： - 要将 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