{{tag>[docker cli buildx buildkit multiarch]}}

====== Docker Buildx ======
BuildKit 기반의 확장 빌드, multi-platform 이미지 생성, builder instance 관리를 담당하는 ''docker buildx'' 그룹.

===== Summary =====
  * 현대 Docker 빌드의 핵심 확장 계층이다.
  * multi-arch 이미지, cache export/import, registry 기반 manifest 생성이 필요하면 보통 ''buildx'' 를 직접 쓴다.
  * builder instance를 따로 만들면 원격 driver나 별도 cache 전략을 사용할 수 있다.

===== Usage =====
<code bash>
docker buildx [OPTIONS] COMMAND
</code>

===== Options =====
  * ''<color #22b14c>**--builder**</color> <color #7092be>NAME</color>'': 사용할 builder instance 강제 지정
  * ''<color #22b14c>**-D**</color>'', ''<color #22b14c>**--debug**</color>'': debug 로그 활성화

===== Command Groups =====
==== Build and Bake ====
  * ''build'': BuildKit 기반 이미지 빌드
    * 주요 옵션: ''-f'', ''-t'', ''--platform'', ''--push'', ''--load'', ''--output'', ''--secret'', ''--ssh'', ''--cache-from'', ''--cache-to'', ''--attest'', ''--sbom'', ''--provenance''
  * ''bake'': HCL/Compose 스타일 정의 파일로 다중 타깃 빌드
    * 주요 옵션: ''-f'', ''--set'', ''--load'', ''--push'', ''--print''

==== Builder Instances ====
  * ''create'': 새 builder instance 생성
    * 주요 옵션: ''--name'', ''--driver'', ''--platform'', ''--use'', ''--bootstrap''
  * ''ls'': builder 목록
  * ''inspect'': 현재 builder 상태와 지원 플랫폼 확인
  * ''use'': 기본 builder 선택
  * ''stop'' / ''rm'': builder 중지 또는 제거

==== Cache and Registry Tools ====
  * ''du'': build cache 사용량 확인
  * ''prune'': build cache 정리
  * ''imagetools'': registry 이미지 manifest 확인/생성
  * ''history'': build record 관련 명령
  * ''policy'': build policy 관련 명령

===== Examples =====
<code bash>
# multi-platform 빌드 후 registry로 바로 업로드
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/team/myapp:latest \
  --push .

# 전용 builder 생성 후 사용
docker buildx create --name ci-builder --driver docker-container --use
docker buildx inspect --bootstrap

# registry manifest 확인
docker buildx imagetools inspect ghcr.io/example/myapp:latest
</code>

===== Troubleshooting =====
  * ''--load'' 는 단일 플랫폼 결과를 로컬 daemon으로 가져오는 데 적합하다. multi-platform 결과는 보통 ''--push'' 와 함께 쓴다.
  * QEMU 에뮬레이션이나 remote builder driver가 필요하면 builder instance 설정을 다시 봐야 한다.
  * CI에서 build cache를 최대한 재사용하려면 ''--cache-from'' / ''--cache-to'' 를 registry 또는 local cache와 함께 설계한다.

===== Help =====
+++ docker buildx --help |
<code text>
Usage:  docker buildx [OPTIONS] COMMAND

Extended build capabilities with BuildKit

Options:
      --builder string   Override the configured builder instance
                         (default "default")
  -D, --debug            Enable debug logging

Management Commands:
  dap         Start debug adapter protocol compatible debugger
  history     Commands to work on build records
  imagetools  Commands to work on images in registry
  policy      Commands for working with build policies

Commands:
  bake        Build from a file
  build       Start a build
  create      Create a new builder instance
  dial-stdio  Proxy current stdio streams to builder instance
  du          Disk usage
  inspect     Inspect current builder instance
  ls          List builder instances
  prune       Remove build cache
  rm          Remove one or more builder instances
  stop        Stop builder instance
  use         Set the current builder instance
  version     Show buildx version information

Run 'docker buildx COMMAND --help' for more information on a command.
</code>
+++

===== See Also =====
  * [[docker:ko]]
  * [[docker:builder]]
  * [[docker:image]]
  * [[docker:manifest]]

===== History =====
  * codex:: 2026-07-06 Added docker buildx subpage with builder instance, cache, and multi-arch build notes.