uv init: Make uv_build the default build backend (from hatchling) (#14661)

Closes #14298

Switch the default build backend for `uv init` from `hatchling` to
`uv_build`.

This change affects the following two commands:

* `uv init --lib`
* `uv init [--app] --package`

It does not affect `uv init` or `uv init --app` without `--package`. `uv
init --build-backend <...>` also works as before.

**Before**

```
$ uv init --lib project
$ cat project/pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "konstin", email = "konstin@mailbox.org" }
]
requires-python = ">=3.13.2"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

**After**

```
$ uv init --lib project
$ cat project/pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "konstin", email = "konstin@mailbox.org" }
]
requires-python = ">=3.13.2"
dependencies = []

[build-system]
requires = ["uv_build>=0.7.20,<0.8"]
build-backend = "uv_build"
```

I cleaned up some tests for consistency in the second commit.

Author: konstin

crates/uv-build-backend/src/metadata.rs

@@ -171,7 +171,7 @@ impl PyProjectToml {
     ///
     /// ```toml
     /// [build-system]
-    /// requires = ["uv_build>=0.4.15,<5"]
+    /// requires = ["uv_build>=0.4.15,<0.5"]
     /// build-backend = "uv_build"
     /// ```
     pub fn check_build_system(&self, uv_version: &str) -> Vec<String> {
@@ -826,7 +826,7 @@ mod tests {
             {payload}
 
             [build-system]
-            requires = ["uv_build>=0.4.15,<5"]
+            requires = ["uv_build>=0.4.15,<0.5"]
             build-backend = "uv_build"
         "#
         }
@@ -909,7 +909,7 @@ mod tests {
             foo-bar = "foo:bar"
 
             [build-system]
-            requires = ["uv_build>=0.4.15,<5"]
+            requires = ["uv_build>=0.4.15,<0.5"]
             build-backend = "uv_build"
         "#
         };
@@ -1036,7 +1036,7 @@ mod tests {
             foo-bar = "foo:bar"
 
             [build-system]
-            requires = ["uv_build>=0.4.15,<5"]
+            requires = ["uv_build>=0.4.15,<0.5"]
             build-backend = "uv_build"
         "#
         };
@@ -1104,7 +1104,7 @@ mod tests {
         let contents = extend_project("");
         let pyproject_toml = PyProjectToml::parse(&contents).unwrap();
         assert_snapshot!(
-            pyproject_toml.check_build_system("1.0.0+test").join("\n"),
+            pyproject_toml.check_build_system("0.4.15+test").join("\n"),
             @""
         );
     }
@@ -1135,7 +1135,7 @@ mod tests {
             version = "0.1.0"
 
             [build-system]
-            requires = ["uv_build>=0.4.15,<5", "wheel"]
+            requires = ["uv_build>=0.4.15,<0.5", "wheel"]
             build-backend = "uv_build"
         "#};
         let pyproject_toml = PyProjectToml::parse(contents).unwrap();
@@ -1171,7 +1171,7 @@ mod tests {
             version = "0.1.0"
 
             [build-system]
-            requires = ["uv_build>=0.4.15,<5"]
+            requires = ["uv_build>=0.4.15,<0.5"]
             build-backend = "setuptools"
         "#};
         let pyproject_toml = PyProjectToml::parse(contents).unwrap();

crates/uv/src/commands/project/init.rs

@@ -63,9 +63,6 @@ pub(crate) async fn init(
     printer: Printer,
     preview: PreviewMode,
 ) -> Result<ExitStatus> {
-    if build_backend == Some(ProjectBuildBackend::Uv) && preview.is_disabled() {
-        warn_user_once!("The uv build backend is experimental and may change without warning");
-    }
     match init_kind {
         InitKind::Script => {
             let Some(path) = explicit_path.as_deref() else {
@@ -596,7 +593,6 @@ async fn init_project(
         author_from,
         no_readme,
         package,
-        preview,
     )?;
 
     if let Some(workspace) = workspace {
@@ -724,7 +720,6 @@ impl InitProjectKind {
         author_from: Option<AuthorFrom>,
         no_readme: bool,
         package: bool,
-        preview: PreviewMode,
     ) -> Result<()> {
         match self {
             InitProjectKind::Application => InitProjectKind::init_application(
@@ -739,7 +734,6 @@ impl InitProjectKind {
                 author_from,
                 no_readme,
                 package,
-                preview,
             ),
             InitProjectKind::Library => InitProjectKind::init_library(
                 name,
@@ -753,7 +747,6 @@ impl InitProjectKind {
                 author_from,
                 no_readme,
                 package,
-                preview,
             ),
         }
     }
@@ -772,7 +765,6 @@ impl InitProjectKind {
         author_from: Option<AuthorFrom>,
         no_readme: bool,
         package: bool,
-        preview: PreviewMode,
     ) -> Result<()> {
         fs_err::create_dir_all(path)?;
 
@@ -805,11 +797,7 @@ impl InitProjectKind {
             }
 
             // Add a build system
-            let build_backend = match build_backend {
-                Some(build_backend) => build_backend,
-                None if preview.is_enabled() => ProjectBuildBackend::Uv,
-                None => ProjectBuildBackend::Hatch,
-            };
+            let build_backend = build_backend.unwrap_or(ProjectBuildBackend::Uv);
             pyproject.push('\n');
             pyproject.push_str(&pyproject_build_system(name, build_backend));
             pyproject_build_backend_prerequisites(name, path, build_backend)?;
@@ -859,7 +847,6 @@ impl InitProjectKind {
         author_from: Option<AuthorFrom>,
         no_readme: bool,
         package: bool,
-        preview: PreviewMode,
     ) -> Result<()> {
         if !package {
             return Err(anyhow!("Library projects must be packaged"));
@@ -880,11 +867,7 @@ impl InitProjectKind {
         );
 
         // Always include a build system if the project is packaged.
-        let build_backend = match build_backend {
-            Some(build_backend) => build_backend,
-            None if preview.is_enabled() => ProjectBuildBackend::Uv,
-            None => ProjectBuildBackend::Hatch,
-        };
+        let build_backend = build_backend.unwrap_or(ProjectBuildBackend::Uv);
         pyproject.push('\n');
         pyproject.push_str(&pyproject_build_system(name, build_backend));
         pyproject_build_backend_prerequisites(name, path, build_backend)?;

crates/uv/tests/it/build.rs

@@ -1439,7 +1439,6 @@ fn build_fast_path() -> Result<()> {
     let built_by_uv = current_dir()?.join("../../scripts/packages/built-by-uv");
 
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output1")), @r###"
@@ -1465,7 +1464,6 @@ fn build_fast_path() -> Result<()> {
         .assert(predicate::path::is_file());
 
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output2"))
@@ -1485,7 +1483,6 @@ fn build_fast_path() -> Result<()> {
         .assert(predicate::path::is_file());
 
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output3"))
@@ -1505,7 +1502,6 @@ fn build_fast_path() -> Result<()> {
         .assert(predicate::path::is_file());
 
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output4"))
@@ -1545,7 +1541,6 @@ fn build_list_files() -> Result<()> {
     // By default, we build the wheel from the source dist, which we need to do even for the list
     // task.
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output1"))
@@ -1601,7 +1596,6 @@ fn build_list_files() -> Result<()> {
         .assert(predicate::path::missing());
 
     uv_snapshot!(context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output2"))
@@ -1670,7 +1664,6 @@ fn build_list_files_errors() -> Result<()> {
     // In CI, we run with link mode settings.
     filters.push(("--link-mode <LINK_MODE> ", ""));
     uv_snapshot!(filters, context.build()
-        .arg("--preview")
         .arg(&built_by_uv)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output1"))
@@ -1694,7 +1687,6 @@ fn build_list_files_errors() -> Result<()> {
     // Windows normalization
     filters.push(("/crates/uv/../../", "/"));
     uv_snapshot!(filters, context.build()
-        .arg("--preview")
         .arg(&anyio_local)
         .arg("--out-dir")
         .arg(context.temp_dir.join("output2"))
@@ -1987,12 +1979,7 @@ fn force_pep517() -> Result<()> {
     // We need to use a real `uv_build` package.
     let context = TestContext::new("3.12").with_exclude_newer("2025-05-27T00:00:00Z");
 
-    context
-        .init()
-        .arg("--build-backend")
-        .arg("uv")
-        .assert()
-        .success();
+    context.init().assert().success();
 
     let pyproject_toml = context.temp_dir.child("pyproject.toml");
     pyproject_toml.write_str(indoc! {r#"
@@ -2026,7 +2013,7 @@ fn force_pep517() -> Result<()> {
 
     ----- stderr -----
     Building source distribution...
-    Error: Missing module directory for `does_not_exist` in `src`. Found: `temp`
+    Error: Missing source directory at: `src`
       × Failed to build `[TEMP_DIR]/`
       ├─▶ The build backend returned an error
       ╰─▶ Call to `uv_build.build_sdist` failed (exit status: 1)

crates/uv/tests/it/build_backend.rs

@@ -222,8 +222,7 @@ fn preserve_executable_bit() -> Result<()> {
     let project_dir = context.temp_dir.path().join("preserve_executable_bit");
     context
         .init()
-        .arg("--build-backend")
-        .arg("uv")
+        .arg("--lib")
         .arg(&project_dir)
         .assert()
         .success();
@@ -296,7 +295,7 @@ fn rename_module() -> Result<()> {
         module-name = "bar"
 
         [build-system]
-        requires = ["uv_build>=0.5,<0.8"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
     "#})?;
 
@@ -377,7 +376,7 @@ fn rename_module_editable_build() -> Result<()> {
         module-name = "bar"
 
         [build-system]
-        requires = ["uv_build>=0.5,<0.8"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
     "#})?;
 
@@ -436,7 +435,7 @@ fn build_module_name_normalization() -> Result<()> {
         version = "1.0.0"
 
         [build-system]
-        requires = ["uv_build>=0.5,<0.8"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
 
         [tool.uv.build-backend]
@@ -548,7 +547,7 @@ fn build_sdist_with_long_path() -> Result<()> {
         version = "1.0.0"
 
         [build-system]
-        requires = ["uv_build>=0.7,<0.8"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
     "#})?;
     context
@@ -591,7 +590,7 @@ fn sdist_error_without_module() -> Result<()> {
         version = "1.0.0"
 
         [build-system]
-        requires = ["uv_build>=0.7,<0.8"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
     "#})?;
 
@@ -661,7 +660,7 @@ fn complex_namespace_packages() -> Result<()> {
             module-name = "{project_name_dist_info}.{part_name}"
 
             [build-system]
-            requires = ["uv_build>=0.5.15,<10000"]
+            requires = ["uv_build>=0.7,<10000"]
             build-backend = "uv_build"
             "#
         };
@@ -770,8 +769,7 @@ fn symlinked_file() -> Result<()> {
     let project = context.temp_dir.child("project");
     context
         .init()
-        .arg("--build-backend")
-        .arg("uv")
+        .arg("--lib")
         .arg(project.path())
         .assert()
         .success();
@@ -783,7 +781,7 @@ fn symlinked_file() -> Result<()> {
         license-files = ["LICENSE"]
 
         [build-system]
-        requires = ["uv_build>=0.5.15,<10000"]
+        requires = ["uv_build>=0.7,<10000"]
         build-backend = "uv_build"
         "#
     })?;

crates/uv/tests/it/common/mod.rs

@@ -664,6 +664,14 @@ impl TestContext {
         ));
         // For wiremock tests
         filters.push((r"127\.0\.0\.1:\d*".to_string(), "[LOCALHOST]".to_string()));
+        // Avoid breaking the tests when bumping the uv version
+        filters.push((
+            format!(
+                r#"requires = \["uv_build>={},<[0-9.]+"\]"#,
+                uv_version::version()
+            ),
+            r#"requires = ["uv_build>=[CURRENT_VERSION],<[NEXT_BREAKING]"]"#.to_string(),
+        ));
 
         Self {
             root: ChildPath::new(root.path()),