处理项目

uv 支持管理 Python 项目，这些项目在其 pyproject.toml 文件中定义了依赖项。

创建新项目

您可以使用 uv init 命令创建一个新的 Python 项目

$ uv init hello-world
$ cd hello-world

或者，您可以在工作目录中初始化一个项目

$ mkdir hello-world
$ cd hello-world
$ uv init

uv 将创建以下文件

├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

main.py 文件包含一个简单的“Hello world”程序。使用 uv run 尝试一下

$ uv run main.py
Hello from hello-world!

项目结构

一个项目由几个重要的部分组成，它们协同工作并允许 uv 管理您的项目。除了 uv init 创建的文件之外，uv 还将在您第一次运行项目命令时，在项目的根目录中创建一个虚拟环境和 uv.lock 文件，例如 uv run、uv sync 或 uv lock。

完整的列表如下所示

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

`pyproject.toml`

pyproject.toml 包含有关您项目的元数据

pyproject.toml

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

您将使用此文件来指定依赖项，以及有关项目的详细信息，例如其描述或许可证。您可以手动编辑此文件，也可以使用 uv add 和 uv remove 等命令从终端管理您的项目。

提示

有关开始使用 pyproject.toml 格式的更多详细信息，请参阅官方 pyproject.toml 指南。

您还可以使用此文件在 [tool.uv] 部分中指定 uv 配置选项。

`.python-version`

.python-version 文件包含项目的默认 Python 版本。此文件告诉 uv 在创建项目的虚拟环境时使用哪个 Python 版本。

`.venv`

.venv 文件夹包含您项目的虚拟环境，这是一个与系统其余部分隔离的 Python 环境。这是 uv 将安装您的项目依赖项的地方。

有关更多详细信息，请参阅项目环境文档。

`uv.lock`

uv.lock 是一个跨平台锁定文件，其中包含有关项目依赖项的精确信息。与用于指定项目广泛要求的 pyproject.toml 不同，锁定文件包含安装在项目环境中的确切解析版本。此文件应检入版本控制，以便在机器之间实现一致且可重现的安装。

uv.lock 是一个人可读的 TOML 文件，但由 uv 管理，不应手动编辑。

有关更多详细信息，请参阅锁定文件文档。

管理依赖

您可以使用 uv add 命令将依赖项添加到 pyproject.toml。这也会更新锁定文件和项目环境

$ uv add requests

您还可以指定版本约束或备用来源

$ # Specify a version constraint
$ uv add 'requests==2.31.0'

$ # Add a git dependency
$ uv add git+https://github.com/psf/requests

如果您从 requirements.txt 文件迁移，可以使用带有 -r 标志的 uv add 从该文件添加所有依赖项

$ # Add all dependencies from `requirements.txt`.
$ uv add -r requirements.txt -c constraints.txt

要删除软件包，可以使用 uv remove

$ uv remove requests

要升级软件包，请运行带有 --upgrade-package 标志的 uv lock

$ uv lock --upgrade-package requests

--upgrade-package 标志将尝试将指定的软件包更新到最新的兼容版本，同时保持锁定文件的其余部分不变。

有关更多详细信息，请参阅有关管理依赖项的文档。

管理版本

uv version 命令可用于读取软件包的版本。

要获取软件包的版本，请运行 uv version

$ uv version
hello-world 0.7.0

要在没有软件包名称的情况下获取版本，请使用 --short 选项

$ uv version --short
0.7.0

要以 JSON 格式获取版本信息，请使用 --output-format json 选项

$ uv version --output-format json
{
    "package_name": "hello-world",
    "version": "0.7.0",
    "commit_info": null
}

有关更新软件包版本的详细信息，请参阅发布指南。

运行命令

uv run 可用于在项目环境中运行任意脚本或命令。

在每次 uv run 调用之前，uv 都会验证锁定文件是否与 pyproject.toml 最新，以及环境是否与锁定文件最新，从而使您的项目保持同步，而无需手动干预。 uv run 保证您的命令在一致的锁定环境中运行。

例如，要使用 flask

$ uv add flask
$ uv run -- flask run -p 3000

或者，要运行脚本

example.py

# Require a project dependency
import flask

print("hello world")

$ uv run example.py

或者，您可以使用 uv sync 手动更新环境，然后在执行命令之前激活它

macOS 和 LinuxWindows

$ uv sync
$ source .venv/bin/activate
$ flask run -p 3000
$ python example.py

PS> uv sync
PS> .venv\Scripts\activate
PS> flask run -p 3000
PS> python example.py

注意

虚拟环境必须处于活动状态才能在项目中运行脚本和命令，而无需 uv run。虚拟环境激活因 shell 和平台而异。

有关更多详细信息，请参阅有关在项目中运行命令和脚本的文档。

构建分发包

uv build 可用于为您的项目构建源代码分发和二进制分发（轮子）。

默认情况下，uv build 将在当前目录中构建项目，并将构建的工件放在 dist/ 子目录中

$ uv build
$ ls dist/
hello-world-0.1.0-py3-none-any.whl
hello-world-0.1.0.tar.gz

有关更多详细信息，请参阅有关构建项目的文档。

下一步

要了解有关使用 uv 处理项目的更多信息，请参阅项目概念页面和命令参考。

或者，请继续阅读以了解如何构建您的项目并将其发布到包索引。