Troubleshooting build failuresビルド失敗のトラブルシューティング
uv needs to build packages when there is not a compatible wheel (a pre-built distribution of the package) available. Building packages can fail for many reasons, some of which may be unrelated to uv itself.uvは、互換性のあるwheel（パッケージの事前ビルドされた配布物）が利用できない場合にパッケージをビルドする必要があります。パッケージのビルドは多くの理由で失敗する可能性があり、そのいくつかはuv自体とは無関係かもしれません。
Recognizing a build failureビルド失敗の認識
An example build failure can be produced by trying to install and old version of numpy on a new, unsupported version of Python:古いバージョンのnumpyを新しい、サポートされていないバージョンのPythonにインストールしようとすることで、ビルド失敗の例が生成される可能性があります：
$ uv pip install -p 3.13 'numpy<1.20'
Resolved 1 package in 62ms
× Failed to build `numpy==1.19.5`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel()` failed (exit status: 1)
[stderr]
Traceback (most recent call last):
File "<string>", line 8, in <module>
from setuptools.build_meta import __legacy__ as backend
File "/home/konsti/.cache/uv/builds-v0/.tmpi4bgKb/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
import distutils.core
ModuleNotFoundError: No module named 'distutils'
hint: `distutils` was removed from the standard library in Python 3.12. Consider adding a constraint (like `numpy >1.19.5`) to avoid building a version of `numpy` that depends
on `distutils`.
Notice that the error message is prefaced by "The build backend returned an error".エラーメッセージの前に「ビルドバックエンドがエラーを返しました」と記載されていることに注意してください。
The build failure includes the [stderr] (and [stdout], if present) from the build backend that
was used for the build. The error logs are not from uv itself.ビルド失敗には、ビルドに使用されたビルドバックエンドからの[stderr]（および[stdout]、存在する場合）が含まれています。エラーログはuv自体からのものではありません。
The message following the ╰─▶ is a hint provided by uv, to help resolve common build failures. A
hint will not be available for all build failures.次のメッセージは╰─▶に続くもので、一般的なビルド失敗を解決するためにuvが提供するヒントです。すべてのビルド失敗に対してヒントが提供されるわけではありません。
Confirming that a build failure is specific to uvビルド失敗がuvに特有であることの確認
Build failures are usually related to your system and the build backend. It is rare that a build failure is specific to uv. You can confirm that the build failure is not related to uv by attempting to reproduce it with pip:ビルド失敗は通常、システムやビルドバックエンドに関連しています。ビルド失敗がuvに特有であることは稀です。pipを使用して再現を試みることで、ビルド失敗がuvに関連していないことを確認できます。
$ uv venv -p 3.13 --seed
$ source .venv/bin/activate
$ pip install --use-pep517 --no-cache --force-reinstall 'numpy==1.19.5'
Collecting numpy==1.19.5
Using cached numpy-1.19.5.zip (7.3 MB)
Installing build dependencies ... done
Getting requirements to build wheel ... done
ERROR: Exception:
Traceback (most recent call last):
...
File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_impl.py", line 321, in _call_hook
raise BackendUnavailable(data.get('traceback', ''))
pip._vendor.pyproject_hooks._impl.BackendUnavailable: Traceback (most recent call last):
File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 77, in _build_backend
obj = import_module(mod_path)
File "/Users/example/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/lib/python3.13/importlib/__init__.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
File "<frozen importlib._bootstrap>", line 1310, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 1022, in exec_module
File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
File "/private/var/folders/6p/k5sd5z7j31b31pq4lhn0l8d80000gn/T/pip-build-env-vdpjme7d/overlay/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
import distutils.core
ModuleNotFoundError: No module named 'distutils'
Important重要
The --use-pep517 flag should be included with the pip install invocation to ensure the same
build isolation behavior. uv always uses build isolation by default.--use-pep517フラグは、pip installの呼び出しに含める必要があります。これにより、同じビルドアイソレーションの動作が保証されます。uvは常にデフォルトでビルドアイソレーションを使用します。
We also recommend including the --force-reinstall and --no-cache options when reproducing
failures.失敗を再現する際には、--force-reinstallおよび--no-cacheオプションを含めることをお勧めします。
Since this build failure occurs in pip too, it is not likely to be a bug with uv.このビルド失敗はpipでも発生するため、uvのバグである可能性は低いです。
If a build failure is reproducible with another installer, you should investigate upstream (in this
example, numpy or setuptools), find a way to avoid building the package in the first place, or
make the necessary adjustments to your system for the build to succeed.別のインストーラーでビルド失敗が再現できる場合は、アップストリーム（この例ではnumpyまたはsetuptools）を調査し、最初にパッケージをビルドしない方法を見つけるか、ビルドが成功するようにシステムに必要な調整を行うべきです。
Why does uv build a package?なぜuvはパッケージをビルドするのか？
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 v2.2+). Only if all of that fails, it builds the
package.クロスプラットフォームのロックファイルを生成する際、uvはすべてのパッケージの依存関係を特定する必要があります。他のプラットフォームにのみインストールされているパッケージも含まれます。uvは解決中にパッケージのビルドを避けようとします。そのバージョンのホイールが存在する場合はそれを使用し、次にソース配布の静的メタデータ（主にpyproject.tomlの静的project.version、project.dependencies、project.optional-dependenciesまたはMETADATA v2.2+）を探します。それらすべてが失敗した場合のみ、パッケージをビルドします。
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.インストール時、uvは各パッケージの現在のプラットフォーム用のホイールを持っている必要があります。インデックスに一致するホイールが存在しない場合、uvはソース配布をビルドしようとします。
You can check which wheels exist for a PyPI project under “Download Files”, e.g.
https://pypi.org/project/numpy/2.1.1.md#files. Wheels with ...-py3-none-any.whl filenames work
everywhere, others have the operating system and platform in the filename. In the linked numpy
example, you can see that there are pre-built distributions for Python 3.10 to 3.13 on macOS, Linux
and Windows.PyPIプロジェクトの「Download Files」セクションで、どのホイールが存在するかを確認できます。例えば、https://pypi.org/project/numpy/2.1.1.md#files。...-py3-none-any.whlというファイル名のホイールはどこでも動作しますが、他のものはファイル名にオペレーティングシステムとプラットフォームが含まれています。リンクされたnumpyの例では、macOS、Linux、Windows用のPython 3.10から3.13までのプリビルドディストリビューションがあることがわかります。
Common build failures一般的なビルドエラー
The following examples demonstrate common build failures and how to resolve them.以下の例は、一般的なビルドエラーとその解決方法を示しています。
Command is not foundコマンドが見つかりません
If the build error mentions a missing command, for example, gcc:ビルドエラーに欠落しているコマンドが言及されている場合、例えばgccの場合：
× Failed to build `pysha3==1.0.2`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
[stdout]
running bdist_wheel
running build
running build_py
creating build/lib.linux-x86_64-cpython-310
copying sha3.py -> build/lib.linux-x86_64-cpython-310
running build_ext
building '_pysha3' extension
creating build/temp.linux-x86_64-cpython-310/Modules/_sha3
gcc -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -fPIC -DPY_WITH_KECCAK=1 -I/root/.cache/uv/builds-v0/.tmp8V4iEk/include -I/usr/local/include/python3.10 -c
Modules/_sha3/sha3module.c -o build/temp.linux-x86_64-cpython-310/Modules/_sha3/sha3module.o
[stderr]
error: command 'gcc' failed: No such file or directory
Then, you'll need to install it with your system package manager, e.g., to resolve the error above:その場合、システムのパッケージマネージャーを使用してインストールする必要があります。例えば、上記のエラーを解決するためには：
Tipヒント
When using the uv-managed Python versions, it's common to need clang installed instead of
gcc.uv管理のPythonバージョンを使用する場合、gccの代わりにclangをインストールする必要があることが一般的です。
Many Linux distributions provide a package that includes all the common build dependencies. You can address most build requirements by installing it, e.g., for Debian or Ubuntu:多くのLinuxディストリビューションは、一般的なビルド依存関係をすべて含むパッケージを提供しています。それをインストールすることで、ほとんどのビルド要件に対処できます。例えば、DebianやUbuntuの場合：
Header or library is missingヘッダーまたはライブラリが欠落しています
If the build error mentions a missing header or library, e.g., a .h file, then you'll need to
install it with your system package manager.ビルドエラーに欠落しているヘッダーまたはライブラリ、例えば.hファイルが言及されている場合、その場合もシステムのパッケージマネージャーを使用してインストールする必要があります。
For example, installing pygraphviz requires Graphviz to be installed:例えば、pygraphvizをインストールするには、Graphvizをインストールする必要があります：
× Failed to build `pygraphviz==1.14`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)
[stdout]
running bdist_wheel
running build
running build_py
...
gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O3 -Wall -fPIC -DSWIG_PYTHON_STRICT_BYTE_CHAR -I/root/.cache/uv/builds-v0/.tmpgLYPe0/include -I/usr/local/include/python3.12 -c pygraphviz/graphviz_wrap.c -o
build/temp.linux-x86_64-cpython-312/pygraphviz/graphviz_wrap.o
[stderr]
...
pygraphviz/graphviz_wrap.c:9: warning: "SWIG_PYTHON_STRICT_BYTE_CHAR" redefined
9 | #define SWIG_PYTHON_STRICT_BYTE_CHAR
|
<command-line>: note: this is the location of the previous definition
pygraphviz/graphviz_wrap.c:3023:10: fatal error: graphviz/cgraph.h: No such file or directory
3023 | #include "graphviz/cgraph.h"
| ^~~~~~~~~~~~~~~~~~~
compilation terminated.
error: command '/usr/bin/gcc' failed with exit code 1
hint: This error likely indicates that you need to install a library that provides "graphviz/cgraph.h" for `pygraphviz@1.14`
To resolve this error on Debian, you'd install the libgraphviz-dev package:Debianでこのエラーを解決するには、libgraphviz-devパッケージをインストールします：
Note that installing the graphviz package is not sufficient, the development headers need to be
installed.なお、graphvizパッケージをインストールするだけでは不十分で、開発ヘッダーもインストールする必要があります。
Tipヒント
To resolve an error where Python.h is missing, install the python3-dev package.Python.hが欠落しているというエラーを解決するには、python3-devパッケージをインストールしてください。
Module is missing or cannot be importedモジュールが見つからないか、インポートできません
If the build error mentions a failing import, consider disabling build isolation.ビルドエラーが失敗したインポートに言及している場合は、ビルドアイソレーションを無効にすることを検討してください。
For example, some packages assume that pip is available without declaring it as a build
dependency:例えば、一部のパッケージは、ビルド依存関係として宣言せずにpipが利用可能であると仮定しています：
× Failed to build `chumpy==0.70`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
[stderr]
Traceback (most recent call last):
File "<string>", line 9, in <module>
ModuleNotFoundError: No module named 'pip'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "<string>", line 14, in <module>
File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 334, in get_requires_for_build_wheel
return self._get_build_requires(config_settings, requirements=[])
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 304, in _get_build_requires
self.run_setup()
File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 522, in run_setup
super().run_setup(setup_script=setup_script)
File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 320, in run_setup
exec(code, locals())
File "<string>", line 11, in <module>
ModuleNotFoundError: No module named 'pip'
To resolve this error, pre-install the build dependencies then disable build isolation for the package:このエラーを解決するには、ビルド依存関係を事前にインストールし、その後パッケージのビルドアイソレーションを無効にします：
Note you will need to install the missing package, e.g., pip, and all the other build
dependencies of the package, e.g, setuptools.欠落しているパッケージ、例えばpip、およびパッケージの他のすべてのビルド依存関係、例えばsetuptoolsをインストールする必要があることに注意してください。
Old version of the package is built古いバージョンのパッケージがビルドされています
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 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.パッケージが解決中にビルドに失敗し、ビルドに失敗したバージョンが使用したいバージョンよりも古い場合は、制約を追加してみてください。下限（例：numpy>=1.17）を指定します。時々、アルゴリズムの制限により、uvリゾルバは不合理に古いパッケージを使用して適合するバージョンを見つけようとすることがあり、下限を使用することでこれを防ぐことができます。
For example, when resolving the following dependencies on Python 3.10, uv attempts to build an old
version of apache-beam.例えば、Python 3.10で以下の依存関係を解決する際に、uvは古いバージョンのapache-beamをビルドしようとします。
× Failed to build `apache-beam==2.0.0`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
[stderr]
...
Adding a lower bound constraint, e.g., apache-beam<=2.49.0,>2.30.0, resolves this build failure as
uv will avoid using an old version of apache-beam.下限制約を追加することで、例えばapache-beam<=2.49.0,>2.30.0、このビルド失敗を解決できます。uvは古いバージョンのapache-beamを使用しないようになります。
Constraints can also be defined for indirect dependencies using constraints.txt files or the
constraint-dependencies setting.制約は、constraints.txtファイルやconstraint-dependencies設定を使用して、間接依存関係にも定義できます。
Old Version of a build dependency is usedビルド依存関係の古いバージョンが使用されています
If a package fails to build because uv selects an incompatible or outdated version of a build-time
dependency, you can enforce constraints specifically for build dependencies. The
build-constraint-dependencies setting (or an
analogous build-constraints.txt file) can be used to ensure that uv selects an appropriate
version of a given build requirements.パッケージがuvによって互換性のないまたは古いビルド時依存関係のバージョンを選択されてビルドに失敗した場合、ビルド依存関係に特化した制約を強制することができます。build-constraint-dependencies設定（または類似のbuild-constraints.txtファイル）を使用して、uvが特定のビルド要件の適切なバージョンを選択することを保証できます。
For example, the issue described in
#5551 could be addressed by
specifying a build constraint that excludes setuptools version 72.0.0:例えば、#5551で説明されている問題は、setuptoolsのバージョン72.0.0を除外するビルド制約を指定することで対処できます：
[tool.uv]
# Prevent setuptools version 72.0.0 from being used as a build dependency.
build-constraint-dependencies = ["setuptools!=72.0.0"]
The build constraint will thus ensure that any package requiring setuptools during the build
process will avoid using the problematic version, preventing build failures caused by incompatible
build dependencies.このビルド制約により、ビルドプロセス中にsetuptoolsを必要とするパッケージは問題のあるバージョンを使用しないようになり、互換性のないビルド依存関係によるビルド失敗を防ぐことができます。
Package is only needed for an unused platformパッケージは未使用のプラットフォームにのみ必要です
If locking fails due to building a package from a platform you do not need to support, consider limiting resolution to your supported platforms.サポートする必要のないプラットフォームからパッケージをビルドすることでロックが失敗した場合は、サポートされているプラットフォームに対して解決を制限することを検討してください。
Package does not support all Python versionsパッケージはすべてのPythonバージョンをサポートしていません
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. For example, numpy only
supports four Python minor version at a time, so to support a wider range of Python versions, e.g.,
Python 3.8 to 3.13, the numpy requirement needs to be split:多くのPythonバージョンをサポートする場合は、古いPythonバージョンには古いバージョンを、新しいPythonバージョンには新しいバージョンを使用するためにマーカーを使用することを検討してください。例えば、numpyは同時に4つのPythonマイナーバージョンしかサポートしていないため、より広範なPythonバージョン、例えばPython 3.8から3.13をサポートするには、numpyの要件を分割する必要があります。
Package is only usable on a specific platformパッケージは特定のプラットフォームでのみ使用可能です
If locking fails due to building a package that is only usable on another platform, you can provide dependency metadata manually to skip the build. uv can not verify this information, so it is important to specify correct metadata when using this override.別のプラットフォームでのみ使用可能なパッケージのビルドに失敗した場合は、ビルドをスキップするために依存関係メタデータを手動で提供できます。uvはこの情報を検証できないため、このオーバーライドを使用する際には正しいメタデータを指定することが重要です。