跳转至

项目开发

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 包含项目的元数据：

pyproject.toml
[project]
name = "hello-world"
version = "0.1.0"
description = "在此处添加项目描述"
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

你还可以指定版本约束或备用源：

$ # 指定版本约束
$ uv add 'requests==2.31.0'

$ # 添加一个 Git 依赖项
$ uv add git+https://github.com/psf/requests

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

$ # 从 `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 run 可用于在项目环境中运行任意脚本或命令。

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

例如，要使用 flask：

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

或者，运行一个脚本：

example.py
# 引入项目依赖
```python
import flask

print("hello world")

$ uv run example.py

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

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

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

注意

若要在不使用 uv run 的情况下运行项目中的脚本和命令，必须激活虚拟环境。虚拟环境的激活方式因 shell 和平台而异。

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

构建发行版

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 处理项目的更多信息，请参阅项目概念页面和命令参考。

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