2.4 处理项目

原文链接: https://docs.astral.sh/uv/guides/projects/

2.4 处理项目

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

创建新项目

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

1
2

$ uv init hello-world
$ cd hello-world

或者，也可以在当前工作目录中初始化项目：

1
2
3

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

uv 会创建以下文件和目录：

1
2
3
4
5
6
7
8

├── .git/
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── src
    └── hello_world
        └── __init__.py

pyproject.toml 定义了一个 hello-world 入口点，指向 __init__.py 中一个简单的 “Hello world” 程序。用 uv run 试试：

1
2

$ uv run hello-world
Hello from hello-world!

项目结构

一个项目由几个重要部分组成，它们协同工作，让 uv 能够管理你的项目。除了 uv init 创建的文件之外，首次运行项目命令（即 uv run、uv sync 或 uv lock）时，uv 还会在项目根目录创建虚拟环境和 uv.lock 文件。

完整的目录结构大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

.
├── .git/
├── .venv/
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .gitignore
├── .python-version
├── README.md
├── src
│   └── hello_world
│       └── __init__.py
├── pyproject.toml
└── uv.lock

pyproject.toml

pyproject.toml 包含项目的元数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
  { name = "ferris", email = "ferris@example.org" }
]
requires-python = ">=3.14"
dependencies = []

[project.scripts]
hello-world = "hello_world:main"

[build-system]
requires = ["uv_build>=0.12.19,<0.13"]
build-backend = "uv_build"

你将使用这个文件指定依赖，以及项目的详细信息，例如描述或许可证。你可以手动编辑该文件，也可以使用 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 添加依赖。这同时会更新锁文件与项目环境：

1

$ uv add requests

你也可以指定版本约束或替代来源：

1
2
3
4
5

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

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

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

1
2

$ # 添加 `requirements.txt` 中的所有依赖。
$ uv add -r requirements.txt -c constraints.txt

要移除某个包，可以使用 uv remove：

1

$ uv remove requests

要升级某个包，请带 --upgrade-package 标志运行 uv lock：

1

$ uv lock --upgrade-package requests

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

更多细节请参阅管理依赖文档。

查看版本

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

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

1
2

$ uv version
hello-world 0.7.0

要只获取版本号而不带包名，请使用 --short 选项：

1
2

$ uv version --short
0.7.0

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

1
2
3
4
5
6

$ 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 保证你的命令运行在一个所有必需依赖都处于锁定版本的环境中。

注意

默认情况下，uv run 不会从环境中移除多余（不在锁文件中）的包。细节请参阅多余包的处理。

例如，使用 flask：

1
2

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

或者，运行一个脚本：

1
2
3
4
5

# example.py
# 需要项目依赖
import flask

print("hello world")

1

$ uv run example.py

另一种方式是使用 uv sync 手动更新环境，然后在执行命令前激活它：

• macOS 和 Linux
• Windows

1
2
3
4

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

1
2
3
4

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

注意

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

更多细节请参阅在项目中运行命令和脚本的文档。

构建分发包

uv build 可用于为项目构建源码分发和二进制分发（wheel）。

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

1
2
3
4

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

更多细节请参阅构建项目文档。

后续步骤

要进一步了解用 uv 处理项目，请参阅项目概念页面和命令参考。

或者继续阅读，了解如何把 uv 锁文件导出为不同格式。