Skip to content

The uv build backenduvビルドバックエンド

A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel.ビルドバックエンドは、ソースツリー（つまり、ディレクトリ）をソース配布またはホイールに変換します。

uv supports all build backends (as specified by PEP 517), but also provides a native build backend (uv_build) that integrates tightly with uv to improve performance and user experience.uvはすべてのビルドバックエンドをサポートしています（PEP 517で指定されています）が、性能とユーザーエクスペリエンスを向上させるためにuvと密接に統合されたネイティブビルドバックエンド（uv_build）も提供しています。

Choosing a build backendビルドバックエンドの選択

The uv build backend is a great choice for most Python projects. It has reasonable defaults, with the goal of requiring zero configuration for most users, but provides flexible configuration to accommodate 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.uvビルドバックエンドは、ほとんどのPythonプロジェクトにとって素晴らしい選択肢です。ほとんどのユーザーに対してゼロ設定を要求することを目指した合理的なデフォルトを持っていますが、ほとんどのPythonプロジェクト構造に対応するための柔軟な設定も提供します。メッセージングとユーザーエクスペリエンスを向上させるためにuvと密接に統合されています。プロジェクトのメタデータと構造を検証し、一般的なミスを防ぎます。そして、最後に、非常に高速です。

The uv build backend currently only supports pure Python code. An alternative backend is required to build a library with extension modules.uvビルドバックエンドは現在純粋なPythonコードのみをサポートしています。拡張モジュールを持つライブラリをビルドするには、別のバックエンドが必要です。

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 build backend instead.バックエンドはプロジェクト構造を構成するための多くのオプションをサポートしていますが、ビルドスクリプトやより柔軟なプロジェクトレイアウトが必要な場合は、代わりにhatchlingビルドバックエンドの使用を検討してください。

Using the uv build backenduvビルドバックエンドの使用

To use uv as a build backend in an existing project, add uv_build to the [build-system] section in your pyproject.toml:既存のプロジェクトでuvをビルドバックエンドとして使用するには、pyproject.tomlの[build-system]セクションにuv_buildを追加します：

pyproject.toml
[build-system]
requires = ["uv_build>=0.9.13,<0.10.0"]
build-backend = "uv_build"

Note注意

The uv build backend follows the same versioning policy as uv. Including an upper bound on the uv_build version ensures that your package continues to build correctly as new versions are released.uvビルドバックエンドは、uvと同じバージョニングポリシーに従います。uv_buildのバージョンに上限を含めることで、新しいバージョンがリリースされてもパッケージが正しくビルドされ続けることを保証します。

To create a new project that uses the uv build backend, use uv init:uvビルドバックエンドを使用する新しいプロジェクトを作成するには、uv initを使用します：

$ uv init

When the project is built, e.g., with uv build, the uv build backend will be used to create the source distribution and wheel.プロジェクトがビルドされると、例えば、uv buildを使用して、uv buildバックエンドがソース配布とホイールを作成するために使用されます。

Bundled build backendバンドルされたビルドバックエンド

The build backend is published as a separate package (uv_build) that is optimized for portability and small binary size. However, the uv executable also includes a copy of the build backend, which will be used during builds performed by uv, e.g., during uv build, if its version is compatible with the uv_build requirement. If it's not compatible, a compatible version of the uv_build package will be used. Other build frontends, such as python -m build, will always use the uv_build package, typically choosing the latest compatible version.ビルドバックエンドは、ポータビリティと小さなバイナリサイズに最適化された別のパッケージ（uv_build）として公開されています。しかし、uv実行可能ファイルにはビルドバックエンドのコピーも含まれており、uv buildなどのuvによって実行されるビルド中に使用されます。そのバージョンがuv_buildの要件と互換性がある場合です。互換性がない場合は、互換性のあるバージョンのuv_buildパッケージが使用されます。他のビルドフロントエンド、例えばpython -m buildは常にuv_buildパッケージを使用し、通常は最新の互換性のあるバージョンを選択します。

Modulesモジュール

Python packages are expected to contain one or more Python modules, which are directories containing an __init__.py. By default, a single root module is expected at src/<package_name>/__init__.py.Pythonパッケージは、1つ以上のPythonモジュールを含むことが期待されており、これらは__init__.pyを含むディレクトリです。デフォルトでは、src/<package_name>/__init__.pyに単一のルートモジュールが期待されます。

For example, the structure for a project named foo would be:例えば、fooという名前のプロジェクトの構造は次のようになります:

pyproject.toml
src
└── foo
    └── __init__.py

uv normalizes the package name to determine the default module name: the package name is lowercased and dots and dashes are replaced with underscores, e.g., Foo-Bar would be converted to foo_bar.uvはパッケージ名を正規化してデフォルトのモジュール名を決定します: パッケージ名は小文字に変換され、ドットとダッシュはアンダースコアに置き換えられます。例えば、Foo-Barはfoo_barに変換されます。

The src/ directory is the default directory for module discovery.src/ディレクトリはモジュール発見のためのデフォルトディレクトリです。

These defaults can be changed with the module-name and module-root settings. For example, to use a FOO module in the root directory, as in the project structure:これらのデフォルトは、module-nameおよびmodule-root設定で変更できます。例えば、プロジェクト構造のようにルートディレクトリにFOOモジュールを使用するには:

pyproject.toml
FOO
└── __init__.py

The correct build configuration would be:正しいビルド構成は次のようになります:

pyproject.toml
[tool.uv.build-backend]
module-name = "FOO"
module-root = ""

Namespace packagesネームスペースパッケージ

Namespace packages are intended for use-cases where multiple packages write modules into a shared namespace.ネームスペースパッケージは、複数のパッケージが共有ネームスペースにモジュールを書き込むユースケースを目的としています。

Namespace package modules are identified by a . in the module-name. For example, to package the module bar in the shared namespace foo, the project structure would be:ネームスペースパッケージモジュールは、.をmodule-nameに含むことで識別されます。たとえば、モジュールbarを共有ネームスペースfooにパッケージ化するには、プロジェクト構造は次のようになります:

pyproject.toml
src
└── foo
    └── bar
        └── __init__.py

And the module-name configuration would be:そして、module-nameの設定は次のようになります:

pyproject.toml
[tool.uv.build-backend]
module-name = "foo.bar"

Important重要

The __init__.py file is not included in foo, since it's the shared namespace module.__init__.pyファイルはfooには含まれません。なぜなら、それは共有ネームスペースモジュールだからです。

It's also possible to have a complex namespace package with more than one root module, e.g., with the project structure:複数のルートモジュールを持つ複雑なネームスペースパッケージを持つことも可能です。たとえば、プロジェクト構造は次のようになります:

pyproject.toml
src
├── foo
│   └── __init__.py
└── bar
    └── __init__.py

While we do not recommend this structure (i.e., you should use a workspace with multiple packages instead), it is supported by setting module-name to a list of names:この構造は推奨されません（つまり、代わりに複数のパッケージを持つワークスペースを使用すべきです）が、module-nameを名前のリストに設定することでサポートされています:

pyproject.toml
[tool.uv.build-backend]
module-name = ["foo", "bar"]

For packages with many modules or complex namespaces, the namespace = true option can be used to avoid explicitly declaring each module name, e.g.:多くのモジュールや複雑なネームスペースを持つパッケージの場合、namespace = trueオプションを使用して、各モジュール名を明示的に宣言することを避けることができます。たとえば:

pyproject.toml
[tool.uv.build-backend]
namespace = true

Warning警告

Using namespace = true disables safety checks. Using an explicit list of module names is strongly recommended outside of legacy projects.namespace = trueを使用すると、安全性チェックが無効になります。レガシープロジェクト以外では、モジュール名の明示的なリストを使用することを強く推奨します。

The namespace option can also be used with module-name to explicitly declare the root, e.g., for the project structure:namespaceオプションは、module-nameとともに使用してルートを明示的に宣言することもできます。たとえば、プロジェクト構造の場合:

pyproject.toml
src
└── foo
    ├── bar
    │   └── __init__.py
    └── baz
        └── __init__.py

The recommended configuration would be:推奨される構成は次のとおりです：

pyproject.toml
[tool.uv.build-backend]
module-name = "foo"
namespace = true

Stub packagesスタブパッケージ

The build backend also supports building type stub packages, which are identified by the -stubs suffix on the package or module name, e.g., foo-stubs. The module name for type stub packages must end in -stubs, so uv will not normalize the - to an underscore. Additionally, uv will search for a __init__.pyi file. For example, the project structure would be:ビルドバックエンドは、-stubsサフィックスがパッケージまたはモジュール名に付いている型スタブパッケージのビルドもサポートしています。例えば、foo-stubsのように。型スタブパッケージのモジュール名は-stubsで終わる必要があるため、uvは-をアンダースコアに正規化しません。さらに、uvは__init__.pyiファイルを探します。例えば、プロジェクト構造は次のようになります：

pyproject.toml
src
└── foo-stubs
    └── __init__.pyi

Type stub modules are also supported for namespace packages.型スタブモジュールは、ネームスペースパッケージにも対応しています。

File inclusion and exclusionファイルのインクルージョンと除外

The build backend is responsible for determining which files in a source tree should be packaged into the distributions.ビルドバックエンドは、ソースツリー内のどのファイルが配布物にパッケージ化されるべきかを決定する責任があります。

To determine which files to include in a source distribution, uv first adds the included files and directories, then removes the excluded files and directories. This means that exclusions always take precedence over inclusions.ソース配布に含めるファイルを決定するために、uvはまず含めるファイルとディレクトリを追加し、その後除外するファイルとディレクトリを削除します。これは、除外が常にインクルージョンよりも優先されることを意味します。

By default, uv excludes __pycache__, *.pyc, and *.pyo.デフォルトでは、uvは__pycache__、*.pyc、および*.pyoを除外します。

When building a source distribution, the following files and directories are included:ソース配布を構築する際に、次のファイルとディレクトリが含まれます：

From these, items matching tool.uv.build-backend.source-exclude and the default excludes are removed.これらの中から、 tool.uv.build-backend.source-excludeおよび デフォルトの除外に一致するアイテムが削除されます。

When building a wheel, the following files and directories are included:ホイールをビルドする際に、以下のファイルとディレクトリが含まれます：

  • The module under tool.uv.build-backend.module-rootモジュールは tool.uv.build-backend.module-rootの下にあります。
  • The files referenced by project.license-files, which are copied into the .dist-info directory.project.license-filesで参照されるファイルは、.dist-infoディレクトリにコピーされます。
  • The project.readme, which is copied into the project metadata.project.readmeは、プロジェクトメタデータにコピーされます。
  • All directories under tool.uv.build-backend.data, which are copied into the .data directory.tool.uv.build-backend.dataの下にあるすべてのディレクトリは、 .dataディレクトリにコピーされます。

From these, tool.uv.build-backend.source-exclude, tool.uv.build-backend.wheel-exclude and the default excludes are removed. The source dist excludes are applied to avoid source tree to wheel source builds including more files than source tree to source distribution to wheel build.これらから、 tool.uv.build-backend.source-exclude、 tool.uv.build-backend.wheel-exclude およびデフォルトの除外が削除されます。ソースディストリビューションの除外は、ソースツリーからホイールソースビルドに含まれるファイルがソースツリーからソースディストリビューションへのホイールビルドよりも多くなるのを避けるために適用されます。

There are no specific wheel includes. There must only be one top level module, and all data files must either be under the module root or in the appropriate data directory. Most packages store small data in the module root alongside the source code.特定のホイールインクルードはありません。トップレベルモジュールは1つだけでなければならず、すべてのデータファイルはモジュールルートの下にあるか、適切な データディレクトリにある必要があります。ほとんどのパッケージは、ソースコードと並んでモジュールルートに小さなデータを保存します。

Tipヒント

When using the uv build backend through a frontend that is not uv, such as pip or python -m build, debug logging can be enabled through environment variables with RUST_LOG=uv=debug or RUST_LOG=uv=verbose. When used through uv, the uv build backend shares the verbosity level of uv.uv以外のフロントエンド（例えばpipやpython -m build）を通じてuvビルドバックエンドを使用する場合、デバッグログは環境変数を通じて有効にできます。 RUST_LOG=uv=debugまたはRUST_LOG=uv=verboseを使用します。uvを通じて使用される場合、uvビルドバックエンドはuvの冗長性レベルを共有します。

Include and exclude syntaxインクルードおよび除外の構文

Includes are anchored, which means that pyproject.toml includes only <root>/pyproject.toml and not <root>/bar/pyproject.toml. To recursively include all files under a directory, use a /** suffix, e.g. src/**. Recursive inclusions are also anchored, e.g., assets/**/sample.csv includes all sample.csv files in <root>/assets or any of its children.インクルードはアンカーされており、つまりpyproject.tomlは<root>/pyproject.tomlのみをインクルードし、 <root>/bar/pyproject.tomlはインクルードしません。ディレクトリ内のすべてのファイルを再帰的にインクルードするには、/**サフィックスを使用します。例えば、src/**です。再帰的インクルードもアンカーされており、例えばassets/**/sample.csvは <root>/assetsまたはその子のいずれかにあるすべてのsample.csvファイルをインクルードします。

Note注意

For performance and reproducibility, avoid patterns without an anchor such as **/sample.csv.パフォーマンスと再現性のために、**/sample.csvのようなアンカーなしのパターンは避けてください。

Excludes are not anchored, which means that __pycache__ excludes all directories named __pycache__ regardless of its parent directory. All children of an exclusion are excluded as well. To anchor a directory, use a / prefix, e.g., /dist will exclude only <root>/dist.除外はアンカーされておらず、つまり__pycache__は親ディレクトリに関係なく、__pycache__という名前のすべてのディレクトリを除外します。除外のすべての子も除外されます。 ディレクトリをアンカーするには、/プレフィックスを使用します。例えば、/distは<root>/distのみを除外します。

All fields accepting patterns use the reduced portable glob syntax from PEP 639, with the addition that characters can be escaped with a backslash.パターンを受け入れるすべてのフィールドは、 PEP 639からの縮小されたポータブルグロブ構文を使用し、文字はバックスラッシュでエスケープできます。