diff --git a/crates/uv-build-frontend/src/error.rs b/crates/uv-build-frontend/src/error.rs index 14b27d1780851..db66c1b5b41e3 100644 --- a/crates/uv-build-frontend/src/error.rs +++ b/crates/uv-build-frontend/src/error.rs @@ -191,8 +191,7 @@ pub struct BuildBackendError { impl Display for BuildBackendError { fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { - writeln!(f, "{} ({})", self.message, self.exit_code)?; - write!(f, "See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions")?; + write!(f, "{} ({})", self.message, self.exit_code)?; let mut non_empty = false; diff --git a/crates/uv/tests/it/build.rs b/crates/uv/tests/it/build.rs index a7ac2aea7054f..2c1a027d9e55d 100644 --- a/crates/uv/tests/it/build.rs +++ b/crates/uv/tests/it/build.rs @@ -889,7 +889,6 @@ fn fail() -> Result<()> { from setuptools import setup IndentationError: unexpected indent error: Build backend failed to determine requirements with `build_sdist()` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions "###); Ok(()) @@ -1330,7 +1329,6 @@ fn build_all_with_failure() -> Result<()> { [PKG] Building wheel from source distribution... Successfully built dist/member_a-0.1.0.tar.gz and dist/member_a-0.1.0-py3-none-any.whl [PKG] error: Build backend failed to determine requirements with `build_sdist()` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions Successfully built dist/project-0.1.0.tar.gz and dist/project-0.1.0-py3-none-any.whl "###); diff --git a/crates/uv/tests/it/edit.rs b/crates/uv/tests/it/edit.rs index 4cf8cb47bccb6..9c5727715e8fe 100644 --- a/crates/uv/tests/it/edit.rs +++ b/crates/uv/tests/it/edit.rs @@ -4895,7 +4895,6 @@ fn fail_to_add_revert_project() -> Result<()> { error: Failed to prepare distributions Caused by: Failed to download and build `pytorch==1.0.2` Caused by: Build backend failed to build wheel through `build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): diff --git a/crates/uv/tests/it/pip_install.rs b/crates/uv/tests/it/pip_install.rs index aeef437ed5e73..dcd47878e2b5b 100644 --- a/crates/uv/tests/it/pip_install.rs +++ b/crates/uv/tests/it/pip_install.rs @@ -237,7 +237,6 @@ dependencies = ["flask==1.0.x"] ----- stderr ----- error: Failed to build: `project @ file://[TEMP_DIR]/path_dep` Caused by: Build backend failed to determine requirements with `build_wheel()` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stdout] configuration error: `project.dependencies[0]` must be pep508 @@ -3996,7 +3995,6 @@ fn no_build_isolation() -> Result<()> { ----- stderr ----- error: Failed to download and build: `anyio @ https://files.pythonhosted.org/packages/db/4d/3970183622f0330d3c23d9b8a5f52e365e50381fd484d08e3285104333d3/anyio-4.3.0.tar.gz` Caused by: Build backend failed to determine metadata through `prepare_metadata_for_build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): @@ -4066,7 +4064,6 @@ fn respect_no_build_isolation_env_var() -> Result<()> { ----- stderr ----- error: Failed to download and build: `anyio @ https://files.pythonhosted.org/packages/db/4d/3970183622f0330d3c23d9b8a5f52e365e50381fd484d08e3285104333d3/anyio-4.3.0.tar.gz` Caused by: Build backend failed to determine metadata through `prepare_metadata_for_build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): @@ -7028,7 +7025,6 @@ fn install_build_isolation_package() -> Result<()> { ----- stderr ----- error: Failed to download and build: `iniconfig @ https://files.pythonhosted.org/packages/d7/4b/cbd8e699e64a6f16ca3a8220661b5f83792b3017d0f79807cb8708d33913/iniconfig-2.0.0.tar.gz` Caused by: Build backend failed to determine metadata through `prepare_metadata_for_build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): @@ -7281,7 +7277,7 @@ fn sklearn() { let filters = std::iter::once((r"exit code: 1", "exit status: 1")) .chain(context.filters()) .collect::>(); - uv_snapshot!(filters, context.pip_install().arg("sklearn"), @r###" + uv_snapshot!(filters, context.pip_install().arg("sklearn"), @r#" success: false exit_code: 1 ----- stdout ----- @@ -7289,7 +7285,6 @@ fn sklearn() { ----- stderr ----- × Failed to download and build `sklearn==0.0.post12` ╰─▶ Build backend failed to determine requirements with `build_wheel()` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] The 'sklearn' PyPI package is deprecated, use 'scikit-learn' @@ -7309,6 +7304,6 @@ fn sklearn() { https://github.com/scikit-learn/sklearn-pypi-package help: `sklearn` is often confused for `scikit-learn` Did you mean to install `scikit-learn` instead? - "### + "# ); } diff --git a/crates/uv/tests/it/sync.rs b/crates/uv/tests/it/sync.rs index 64d448adb9ff0..095c0b4fee43d 100644 --- a/crates/uv/tests/it/sync.rs +++ b/crates/uv/tests/it/sync.rs @@ -577,7 +577,6 @@ fn sync_build_isolation_package() -> Result<()> { error: Failed to prepare distributions Caused by: Failed to download and build `source-distribution @ https://files.pythonhosted.org/packages/10/1f/57aa4cce1b1abf6b433106676e15f9fa2c92ed2bd4cf77c3b50a9e9ac773/source_distribution-0.0.1.tar.gz` Caused by: Build backend failed to build wheel through `build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): @@ -669,7 +668,6 @@ fn sync_build_isolation_extra() -> Result<()> { error: Failed to prepare distributions Caused by: Failed to download and build `source-distribution @ https://files.pythonhosted.org/packages/10/1f/57aa4cce1b1abf6b433106676e15f9fa2c92ed2bd4cf77c3b50a9e9ac773/source_distribution-0.0.1.tar.gz` Caused by: Build backend failed to build wheel through `build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): @@ -689,7 +687,6 @@ fn sync_build_isolation_extra() -> Result<()> { error: Failed to prepare distributions Caused by: Failed to download and build `source-distribution @ https://files.pythonhosted.org/packages/10/1f/57aa4cce1b1abf6b433106676e15f9fa2c92ed2bd4cf77c3b50a9e9ac773/source_distribution-0.0.1.tar.gz` Caused by: Build backend failed to build wheel through `build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stderr] Traceback (most recent call last): diff --git a/crates/uv/tests/it/tool_install.rs b/crates/uv/tests/it/tool_install.rs index 9d4bec09a9525..c827e3bc9ebc1 100644 --- a/crates/uv/tests/it/tool_install.rs +++ b/crates/uv/tests/it/tool_install.rs @@ -1423,7 +1423,6 @@ fn tool_install_uninstallable() { error: Failed to prepare distributions Caused by: Failed to download and build `pyenv==0.0.1` Caused by: Build backend failed to build wheel through `build_wheel` (exit status: 1) - See https://docs.astral.sh/uv/reference/build_failures/ for common causes and solutions [stdout] running bdist_wheel diff --git a/docs/reference/build_failures.md b/docs/reference/build_failures.md deleted file mode 100644 index 56c30079ff4d1..0000000000000 --- a/docs/reference/build_failures.md +++ /dev/null @@ -1,62 +0,0 @@ -# Build failures - -This page lists common reasons why resolution and installation fails with a build error and how to -fix them. - -### Why does uv build a package? - -When generating the cross-platform lockfile, uv needs to determine the dependencies of all packages, -even those only installed on other platforms. uv tries to avoid package builds during resolution. It -uses any wheel if exist for that version, then tries to find static metadata in the source -distribution (mainly pyproject.toml with static `project.version`, `project.dependencies` and -`project.optional-dependencies` or METADATA of at least version 2.2). Only if all of that fails, it -builds the package. - -When installing, uv needs to have a wheel for the current platform for each package. If no matching -wheel exists in the index, uv tries to build the source distribution. - -You can check which wheels exist for a PyPI project under “Download Files”, e.g. -https://pypi.org/project/numpy/2.1.1/#files. Wheels with `...-py3-none-any.whl` filenames work -everywhere, others have the operating system and platform in the filename. For the linked numpy -version, you can see that Python 3.10 to 3.13 on MacOS, Linux and Windows are supported. - -### Fixes and Workarounds - -- If the build error mentions a missing header or library, there is often a matching package in your - system package manager. - - Example: When `uv pip install mysqlclient==2.2.4` fails on Ubuntu, you need to run - `sudo apt install default-libmysqlclient-dev build-essential pkg-config` to install the MySQL - headers ([https://pypi.org/project/mysqlclient/2.2.4/](https://pypi.org/project/mysqlclient/2.2.4/#Linux)) - -- If the build error mentions a failing import, consider - [deactivating build isolation](https://docs.astral.sh/uv/concepts/projects/#build-isolation). -- If a package fails to build during resolution and the version that failed to build is older than - the version you want to use, try adding a - [constraint](https://docs.astral.sh/uv/reference/settings/#constraint-dependencies) with a lower - bound (e.g. `numpy>=1.17`). Sometimes, due to algorithmic limitations, the uv resolver tries to - find a fitting version using unreasonably old packages, which can be prevented by using lower - bounds. -- Consider using a different Python version for locking and/or installation (`-p`). If you are using - an older Python version, you may need to use an older version of certain packages with native code - too, especially for scientific code. Example: torch 1.12.0 support Python 3.7 to 3.10 - (https://pypi.org/project/torch/1.12.0/#files), while numpy 2.1.0 supports Python 3.10 to 3.13 - (https://numpy.org/doc/stable/release/2.1.0-notes.html#numpy-2-1-0-release-notes), so both - together mean you need Python 3.10 (or upgrade torch). -- If locking fails due to building a package from a platform you do not support, consider - [declaring resolver environments](https://docs.astral.sh/uv/reference/settings/#environments) with - your supported platforms. -- If you support a large range of Python versions, consider using markers to use older versions for - older Python versions and newer versions for newer Python version. In the example, numpy tends to - support four Python minor version at a time, so to support Python 3.8 to 3.13, the versions need - to be split: - - ``` - numpy>=1.23; python_version >= "3.10" - numpy<1.23; python_version < "3.10" - ``` - -- If locking fails due to building a package from a different platform, as an escape hatch you can - [provide dependency metadata manually](https://docs.astral.sh/uv/reference/settings/#dependency-metadata). - As uv can not verify this information, it is important to specify correct metadata in this - override. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index b8817b5ebe2cc..eff7a40589377 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -129,7 +129,6 @@ nav: - reference/index.md - Commands: reference/cli.md - Settings: reference/settings.md - - Build Failures: reference/build_failures.md - Resolver: reference/resolver-internals.md - Benchmarks: reference/benchmarks.md - Versioning: reference/versioning.md