docker buildx build¶

使い方 ¶

$ docker buildx build [OPTIONS] PATH | URL | -

補足説明 ¶

buildx build コマンドは BuildKit を使って構築を開始します。このコマンドは docker build コマンドの見た目と似ており、いくつかのフラグや引数が同じです。

ほとんどのフラグに関するドキュメントは docker build のドキュメントをご覧ください。ここでは新しいフラグのサブセットを説明します。

コマンドの使用例は、以下の使用例のセクションをご覧ください。

オプション ¶

名前, 省略形	デフォルト	説明
`--add-host`		任意のホストに対し IP を割り当てを追加（書式： `host:ip` ）
`--allow`		拡張特権資格(extra privileged entitlement) を許可（例： `network.host` , `security.insecure` ）
`--build-arg`		構築時の変数を設定
`--cache-from`		外部キャッシュのソース（例： `ser/app:cache` , `type=local,src=path/to/dir` ）
`--cache-to`		外部キャッシュの宛先（例： `ser/app:cache` , `type=local,src=path/to/dir` ）
`--cgroup-parent`		コンテナに対する任意の親 cgroup
`--compress`		構築コンテクストを gzip を使って圧縮
`--cpu-period`		CPU CFS (completely Fair Scheduler)期間を制限
`--cpu-quota`		CPU CFS (completely Fair Scheduler)クォータを制限
`--cpu-shares` 、 `-c`		CPU 配分(share) （相対ウェイト）
`--cpuset-cpus`		アクセスを許可する CPU を指定（ 0-3, 0, 1 ）
`--cpuset-mems`		アクセスを許可するメモリノードを指定（ 0-3, 0, 1 ）
`--file` 、 `-f`		Dockerfile の名前（デフォルトは `パス/Dockerfile` ）
`--force-rm`		中間コンテナを常に削除
`--iidfile`		イメージ ID をファイルに書き込む
`--isolation`		コンテナ分離技術
`--label`		イメージにメタデータを設定
`--load`		`--output=type=docker` の省略形
`--memory` 、 `-m`		メモリの上限
`--memory-swap`		スワップの上限は、メモリとスワップの合計と同じ： `-1` はスワップを無制限にする
`--metadata-file`		構築結果のメタデータをファイルに書き込む
`--network`		構築中の RUN 命令で使うネットワークモードを指定
`--no-cache`		イメージの構築時にキャッシュを使用しない
`--output` 、 `-o`		アウトプット先を指定（書式：type=local,dest=path）
`--platform`		サーバがマルチプラットフォーム対応であれば、プラットフォームを指定
`--progress`	`auto`	進行状況の出力タイプを設定（auto、plain、tty）。plain を使うと、コンテナの出力を表示
`--pull`		イメージは、常に新しいバージョンのダウンロードを試みる
`--push`		`--output=type=registry` の省略形
`--quiet` 、 `-q`		構築時の出力と成功時のイメージ ID 表示を抑制
`--rm`	`true`	構築に成功後、中間コンテナを削除
`--secret`		構築時に利用するシークレットファイル（書式： `id=mysecret,src=/local/secret` ）
`--security-opt`		セキュリティのオプション
`--shm-size`		`/dev/shm` の容量
`--squash`		構築するレイヤを、単一の新しいレイヤに押し込む(squash)
`--ssh`		構築時に利用する SSH エージェントのソケットやキー（書式： `default \| <id>[=<socket>] \| <key>[,<key>]]` ）
`--tag` 、 `-t`		名前と、オプションでタグを `名前:タグ` の形式で指定
`--target`		構築する対象の構築ステージを指定
`--ulimit`		ulimit オプション
`--builder`		ビルダー・インスタンス設定を上書き

使用例 ¶

builder 対象の設定を上書き (--builder)¶

buildx --builder と同じです。

構築対象のプラットフォームを指定 ¶

--platform=value[,value]

構築対象のプラットフォームを指定します。Dockerfile 内にある全ての FROM 命令は、 --platform フラグがなければ、自身のプラットフォーム用のイメージを取得します。そして、最終的なイメージのプラットフォームも自身のものとなります。デフォルトの値は、buildkit デーモンが動作しているプラットフォームです。

buildx で docker-container ドライバを使う場合は、フラグに対してカンマ区切りで複数の値を指定できます。複数の値を指定した結果は、指定したプラットフォームすべてに対して構築し、1つのマニフェストリストに連結します。

Dockerfile で RUN 命令を実行する必要がある場合、ビルダは指定したプラットフォーム用のランタイムをサポートする必要があります。クリーンセットアップの場合、ビルダは自らのシステムアーキテクチャ用のランタイムのサポートが必要です。カーネルが binfmt_misc ランチャーをセカンダリ・アーキテクチャとしてサポートしている場合、buildx はそれらを自動的に対応します。Docker デスクトップ版は binfmt_misc を備えており、 arm64 と arm アーキテクチャに自動的に対応しています。現在のビルダ・インスタンスが対応しているランタイム・プラットフォームを確認するには、 docker buildx inspect --bootstrap を実行します。

Dockerfile 内では、 ``TARGETPLATFORM `` build 引数よって現在のプラットフォーム値を取得できます。自動プラットフォーム引数の種類は、 docker build ドキュメントをご覧ください。

プラットフォームの指定形式は containerd ソースコードで定義されています。

使用例 ¶

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

進捗の出力形式を指定（--progress）¶

--progress=VALUE

進捗の出力形式を指定します（ auto、plain、tty）。plain を使うとコンテナの出力を表示します（デフォルトは auto ）。

注釈

値を指定するには、BUILDKIT_PROGRESS 環境変数の値も利用できます。

以下は、構築中に plain 出力を使う例です。

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s
#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

構築結果の出力方法を指定（-o, --output）¶

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

build 結果の出力処理を設定します。 docker build で全ての構築が終わると、コンテナのイメージを作成し、それを docker images に出力します。 buildx ではこの手順が設定できるようになっており、処理結果を直接クライアントや、oci イメージ・tar ボールやレジストリ等に出力できます。

Buildx の docker ドライバが現時点でサポートしているのは、 local 、 tar ボール・エクスポータ(tarball exporter) とイメージ・エクスポータ(image exporter) のみです。 docker-container ドライバは全てのエクスポータをサポートします。

値にパスを指定した場合には、 buidx はローカル・エクスポータ(local exporter) でこのパスを出力先に使います。もしも値が「-」であれば、 buildx は tar エクスポータを使い stdout に書き出します。

使用例

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

サポートしているエクスポータは以下の通りです。

`local`¶

local エクスポート型は、全ての結果をクライアント上のディレクトリにあるファイルへ書き出します。新しいファイルの所有者は現在のユーザになります。マルチプラットフォーム・ビルドでは、各プラットフォーム用のサブディレクトリに結果が出力されます。

属性のキー：

dest - ファイル出力先のディレクトリ

tar ¶

tar エクスポート型は、全ての結果をクライアント上の tar ボールに書き出します。マルチプラットフォーム・ビルドでは、各プラットフォーム用のサブディレクトリに結果が出力されます。

属性のキー：

dest - tar ボール出力先のディレクトリ。 - は標準出力に書き出す

`oci`¶

oci エクスポート型は、全ての結果をクライアント上の OCI イメージ・レイアウトに書き出します。

属性のキー：

dest - tar ボール出力先のディレクトリ。 - は標準出力に書き出す

`docker`¶

docker エクスポート型は、特定のプラットフォームに対する Docker イメージ仕様のイメージとしてクライアント上に書き出します。このエクスポータによって作成される tar ボールは、 OCI 互換性もあります。

現時点では、マルチプラットフォーム・イメージは docker エクスポート型はでは出力できません。マルチプラットフォーム対応イメージの最も一般的な利用方法は、レジストリに直接送信する場合です（ registry をご覧ください。）。

属性のキー：

dest - tarボール出力先のパス。このパスの指定が無い場合、tar は現在の Docker インスタンスへ自動的に読み込む
context - 結果をインポートする docker コンテクスト名です

`image`¶

image エクスポータは、構築結果をイメージまたはマニフェストリストとして出力します。 docker ドライバでイメージを使う場合は、docker イメージとして出力されます。オプションとして、属性の指定によってイメージを自動的にレジストリに送信できます。

属性のキー：

name - 新しいイメージの名前（リファレンス）
push - 自動的にイメージを送信するかどうかを bollean（0か1）で指定

`registry`¶

registry エクスポータは type=image,push=true の省略形です。

構築結果をレジストリに送信（--push）¶

--output=type=registry の省略形です。構築結果をレジストリに自動送信します。

単一プラットフォームの構築結果を `docker images` に読み込む（--load）¶

--output=type=docker の省略形です。単一プラットフォーム向けの構築結果を docker images に読み込みます。

構築用に外部のキャッシュソースを使用（--cache-from）¶

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

構築用に外部のキャッシュソースを使います。サポートしている型は registry 、 local 、gha です。

registry … registry ソースは、キャッシュ・マニフェストやレジストリ上の（特別な）設定からキャシュを取り込めます。
local … local ソースは、以前に --cache-to で出力済みのロールファイルから、キャッシュを取り込めます。
gha … gha ソースは、以前に --cache-to で GitHub リポジトリに出力済みのキャッシュから、キャッシュを取り込めます。

型（タイプ）を指定しなければ、 registry エクスポータが指定された参照先として使われます。

docker ドライバでは、現時点でサポートしているのは、レジストリからの構築キャッシュ取り込みだけです。

使用例 ¶

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .

キャッシュエクスポータと利用可能な属性については、こちらをご覧ください：https://github.com/moby/buildkit#export-cache

構築キャッシュを外部のキャッシュ先へ出力（--cache-to）¶

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

外部のキャッシュ先に構築キャッシュを出力します。サポートしている型は registry 、 local 、 inline 、 gha です。

registry … registry 型は、構築キャッシュをレジストリ内のキャッシュ・マニフェストに出力します。
local … local 型は、クライアント上のローカルディレクトリへキャッシュを出力します。
inline … inline 型は、イメージ設定内部のキャッシュ・メタデータに出力します。
gha … gha 型は Github Actions Cache service API を通してキャッシュを出力します。

docker ドライバが現時点でサポートしているのは、イメージ設定内部のキャッシュ・メタデータに直接（インラインに）出力するだけです。別の方法として、 --build-arg BUILDKIT_INLINE_CACHE=1 をインライン・キャッシュ・エクスポータのトリガとして使えます。

属性のキー：

mode … キャッシュがどれだけのレイヤに対応するかを指定します。 min は最終構築ステージのレイヤのみ出力します。 max は全ステージのレイヤを出力します。メタデータは構築全体を通し、常に出力します。

使用例 ¶

$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .

キャッシュ・エクスポータと利用可能な属性については、 https://github.com/moby/buildkit#export-cache をご覧ください。

拡張特権資格(extra privileged entitlement) を許可（--allow）¶

--allow=ENTITLEMENT

拡張特権資格(extra privileged entitlement) を許可します。資格（entitlement）の一覧はこちらです：

network.host … ホストネットワーク機能の実行を許可します。
security.insecure … サンドボックス無しでの実行を許可。関連する Dockerfile 拡張をご覧ください。

資格の有効化には、 buildkit デーモンも --allow-insecure-entitlement を許可する必要があります（ create --buildkit-flags をご覧ください）。

使用例 ¶

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

`/dev/shm` の容量（--shm-size）¶

書式は <数値><単位> です。 数値 は 0 より大きい必要があります。単位はオプションで指定でき、 b （バイト）、 k （キロバイト）、 m （メガバイト）、 g （ギガバイト）が使えます。単位を省略すると、システムはバイトとして扱います。

ulimit の設定（--ulimit）¶

--ulimit はソフトリミット(soft limit) とハードリミット(hard limit) を指定します。書式は <type>=<ソフトリミット>[:<ハードリミット>] です。以下は例です。

$ docker buildx build --ulimit nofile=1024:1024 .

注釈

hard limit を指定しない場合、 soft limit が両方の値として用いられます。 ulimits の指定が無ければ、デーモン上のデフォルト ulimits を継承します。

親コマンド ¶

コマンド	説明
docker buildx	Docker Buildx

コマンド	説明
docker buildx bake	ファイルから構築
docker buildx build	構築開始
docker buildx create	新しいビルダー・インスタンスを作成
docker buildx du	ディスク使用量
docker buildx imagetools	レジストリにあるイメージを操作するコマンド
docker buildx inspect	現在のビルダー・インスタンスを調査
docker buildx ls	ビルダー・インスタンス一覧
docker buildx prune	構築キャッシュの削除
docker buildx rm	ビルダー・インスタンスの削除
docker buildx stop	ビルダー・インスタンスの停止
docker buildx use	現在のビルダー・インスタンスを設定
docker buildx version	buildx バージョン情報を表示