3.4.1 项目结构与文件
3 分钟阅读
3.4.1 项目结构与文件
pyproject.toml
Python 项目元数据定义在 pyproject.toml 文件中。uv 需要该文件来识别项目的根目录。
提示
可以用
uv init创建新项目。细节请参阅创建项目。
最小的项目定义包含名称和版本：
| |
其他项目元数据与配置包括：
项目环境
用 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以禁用项目的自动锁定和同步。例如：
1 2 3# pyproject.toml [tool.uv] managed = false
集中式项目环境
借助 centralized-project-envs 预览特性，uv 会把默认项目环境存放在缓存中。uv 会尝试维护一个指向缓存环境的 .venv 目录链接，以便现有的激活和编辑器工作流继续使用通常的路径。如果链接创建失败，uv 会尝试把缓存环境路径写入 .venv。如果两次尝试都失败，uv 会继续直接使用缓存环境，但依赖 .venv 的工具可能无法发现它。切换解释器会选中不同的缓存环境，并可在之后复用它们。
显式的项目环境路径（包括 UV_PROJECT_ENVIRONMENT 和通过 --active 选择的环境）不会被集中管理。启用 --no-cache 时该特性无效。
该特性同样适用于从项目或工作区根目录执行的无路径 uv venv 调用。
锁文件
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 生成“已锁定”的 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 - 要从一组 requirements 生成
pylock.toml文件，请运行：uv pip compile requirements.in -o pylock.toml - 要从
pylock.toml文件安装，请运行：uv pip sync pylock.toml或uv pip install -r pylock.toml