From a7aa46acc571f20cf3fb2ce6fb26219ccbbd44f6 Mon Sep 17 00:00:00 2001 From: konsti Date: Wed, 2 Jul 2025 16:02:03 +0200 Subject: [PATCH] Add a "choosing a build backend" section to the docs (#14295) I think the build backend docs as a whole are now ready for review. I only made a small change here. --------- Co-authored-by: Zanie Blue --- docs/concepts/build-backend.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/concepts/build-backend.md b/docs/concepts/build-backend.md index c78fa55a9..d70f00282 100644 --- a/docs/concepts/build-backend.md +++ b/docs/concepts/build-backend.md @@ -12,13 +12,26 @@ uv supports all build backends (as specified by [PEP 517](https://peps.python.or also provides a native build backend (`uv_build`) that integrates tightly with uv to improve performance and user experience. +## Choosing a build backend + +The uv build backend is a good choice for most Python projects that are using uv. It has reasonable +defaults, with the goal of requiring zero configuration for most users, but provides flexible +configuration that allows most Python project structures. It integrates tightly with uv, to improve +messaging and user experience. It validates project metadata and structures, preventing common +mistakes. And, finally, it's very fast. + +The uv build backend currently **only supports pure Python code**. An alternative backend is +required to build a +[library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). + +!!! tip + + While the backend supports a number of options for configuring your project structure, when build scripts or + a more flexible project layout are required, consider using the + [hatchling](https://hatch.pypa.io/latest/config/build/#build-system) build backend instead. + ## Using the uv build backend -!!! important - - The uv build backend currently **only supports pure Python code**. An alternative backend is to - build a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). - To use uv as a build backend in an existing project, add `uv_build` to the [`[build-system]`](../concepts/projects/config.md#build-systems) section in your `pyproject.toml`: