项目工作

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

创建新项目

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

$ uv init hello-world
$ cd hello-world

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

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

uv将创建以下文件：

.
├── .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 run、 uv sync或uv lock），uv会在项目根目录下创建一个虚拟环境和uv.lock文件。

完整列表如下所示：

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

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等命令从终端管理您的项目。

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

.python-version

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

.venv

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

查看项目环境文档以获取更多详情。

uv.lock

uv.lock 是一个跨平台的锁文件，它包含了项目依赖项的精确信息。与用于指定项目大致需求的 pyproject.toml 不同，锁文件记录了项目环境中实际安装的已解析版本。该文件应当纳入版本控制，以确保在不同机器上能够实现一致且可复现的安装。

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

查看lockfile文档获取更多详情。

管理依赖项

你可以使用uv add命令向你的pyproject.toml添加依赖项。这也会同时更新锁定文件（lockfile）和项目环境：

$ 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文件迁移，可以使用uv add命令并加上-r参数来添加该文件中的所有依赖项：

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

要移除一个包，你可以使用uv remove:

$ uv remove requests

要升级一个包，使用uv lock命令并加上--upgrade-package标志：

$ uv lock --upgrade-package requests

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

更多详情请参阅管理依赖项的文档。

运行命令

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

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

例如，要使用 flask：

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

或者，要运行一个脚本：

# Require a project dependency
import flask

print("hello world")

$ uv run example.py

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

$ 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 build 可用于为您的项目构建源码分发版和二进制分发版（wheel）。

默认情况下，uv build 会在当前目录构建项目，并将构建产物放置在 dist/ 子目录中：

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

更多详情请参阅构建项目的文档。

下一步

要了解更多关于使用uv进行项目工作的信息，请参阅 项目概念页面和 命令参考。

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