创建项目
uv 支持使用 uv init 创建项目。
创建项目时，uv 支持两种基本模板：应用程序 和 库。默认情况下，uv 将创建一个应用程序项目。可以使用 --lib 标志来创建库项目。
目标目录
uv 将在当前工作目录中创建项目，或者通过指定名称在目标目录中创建项目，例如 uv init foo。如果目标目录中已经存在项目，即如果存在 pyproject.toml，uv 将报错退出。
应用程序
应用程序项目适用于 Web 服务器、脚本和命令行界面。
应用程序是 uv init 的默认目标，也可以使用 --app 标志指定。
该项目包括一个 pyproject.toml、一个示例文件（main.py）、一个自述文件和一个 Python 版本锁定文件（.python-version）。
注意
在 v0.6.0 之前，uv 创建的文件名为 hello.py 而非 main.py。
pyproject.toml 包含基本元数据。它不包含构建系统，它不是一个 包，也不会安装到环境中：
[project]
name = "example-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
示例文件使用一些标准样板代码定义了一个 main 函数：
可以使用 uv run 执行 Python 文件：
打包应用程序
许多用例需要打包。例如，如果你正在创建一个将发布到 PyPI 的命令行界面，或者你想在一个专用目录中定义测试。
可以使用 --package 标志来创建一个打包应用程序：
源代码会被移动到一个 src 目录中，该目录包含一个模块目录和一个 __init__.py 文件：
$ tree example-pkg
example-pkg
├── .python-version
├── README.md
├── pyproject.toml
└── src
└── example_pkg
└── __init__.py
会定义一个构建系统，这样项目就会被安装到环境中：
[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
[project.scripts]
example-pkg = "example_pkg:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Tip
可以使用 --build-backend 选项来请求使用其他构建系统。
还会包含一个命令定义：
[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
[project.scripts]
example-pkg = "example_pkg:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
可以使用 uv run 来执行该命令：
库
库为其他项目提供可使用的函数和对象。库旨在构建并分发，例如，将它们上传到 PyPI。
可以使用 --lib 标志创建库：
注意
使用 --lib 意味着使用 --package。库始终需要一个打包的项目。
与打包应用程序一样，使用 src 布局。会包含一个 py.typed 标记，向使用者表明可以从库中读取类型：
$ tree example-lib
example-lib
├── .python-version
├── README.md
├── pyproject.toml
└── src
└── example_lib
├── py.typed
└── __init__.py
注意
在开发库时，src 布局特别有用。它确保库与项目根目录中的任何 python 调用隔离开来，并且确保分发的库代码与项目的其余源代码很好地分离。
定义了一个构建系统，因此项目将安装到环境中：
[project]
name = "example-lib"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
提示
你可以通过在 hatchling、uv_build、flit-core、pdm-backend、setuptools、maturin 或 scikit-build-core 中使用 --build-backend 来选择不同的构建后端模板。如果你想创建一个带扩展模块的库，则需要使用替代后端。
创建的模块定义了一个简单的 API 函数：
你可以使用 uv run 导入并执行它：
$ cd example-lib
$ uv run python -c "import example_lib; print(example_lib.hello())"
Hello from example-lib!
包含扩展模块的项目
大多数 Python 项目是 “纯 Python” 项目，这意味着它们不会用 C、C++、FORTRAN 或 Rust 等其他语言定义模块。不过，包含扩展模块的项目常用于对性能敏感的代码。
创建包含扩展模块的项目需要选择其他构建系统。uv 支持使用以下能构建扩展模块的构建系统来创建项目：
- 基于 Rust 的项目使用maturin
- 基于 C、C++、FORTRAN、Cython 的项目使用scikit-build-core
使用 --build-backend 标志指定构建系统：
注意
使用 --build-backend 意味着同时使用 --package。
该项目除了典型的 Python 项目文件外，还包含一个 Cargo.toml 和一个 lib.rs 文件：
$ tree example-ext
example-ext
├── .python-version
├── Cargo.toml
├── README.md
├── pyproject.toml
└── src
├── lib.rs
└── example_ext
├── __init__.py
└── _core.pyi
注意
如果使用 scikit-build-core，你看到的将是 CMake 配置和 main.cpp 文件。
Rust 库定义了一个简单的函数：
use pyo3::prelude::*;
#[pyfunction]
fn hello_from_bin() -> String {
"Hello from example-ext!".to_string()
}
#[pymodule]
fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_function(wrap_pyfunction!(hello_from_bin, m)?)?;
Ok(())
}
Python 模块导入该函数：
from example_ext._core import hello_from_bin
def main() -> None:
print(hello_from_bin())
可以使用 uv run 执行该命令：
重要
对 lib.rs 或 main.cpp 中扩展代码的更改需要运行 --reinstall 来重新构建它们。
创建最小化项目
如果您只想创建一个 pyproject.toml，请使用 --bare 选项：
uv 将跳过创建 Python 版本锁定文件、README 以及任何源目录或文件。
此外，uv 不会初始化版本控制系统（即 git）。
uv 也不会向 pyproject.toml 添加额外的元数据，例如 description 或 authors。
--bare 选项可以与其他选项（如 --lib 或 --build-backend）一起使用 —— 在这些情况下，uv 仍将配置构建系统，但不会创建预期的文件结构。
使用 --bare 时，仍可选择使用其他功能：