Docker Buildx Build는 기본적으로 BuildKit 기반으로 동작하며 일반적인 docker build와 다른 방식으로 이미지를 처리합니다.
특히 Docker Buildx Build를 사용하면 빌드한 이미지가 바로 로컬 Docker 이미지 목록에 표시되지 않는 경우가 있습니다.
예:
docker buildx build \
-t my-app:v1 .빌드는 성공했지만:
docker images에서 이미지가 보이지 않을 수 있습니다.
이런 경우 사용하는 옵션이 바로 **--load**입니다.
Docker Buildx Build --load 옵션은 빌드한 이미지를 현재 Docker Engine의 로컬 이미지 저장소에 가져오는 기능입니다.
즉, 빌드 결과를 로컬에서 바로 실행하거나 테스트할 수 있도록 만들어 줍니다.
이번 글에서는 Docker Buildx Build –load의 개념부터 기본 사용법, –push와 차이점, 로컬 테스트 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –load란 무엇인가?
--load는 Buildx로 생성한 이미지를 로컬 Docker 이미지 저장소에 저장하는 옵션입니다.
기본 형식:
docker buildx build \
--load \
-t 이미지명 .빌드 과정:
Dockerfile
↓
Buildx Build
↓
이미지 생성
↓
Local Docker Engine 저장저장 후:
docker images명령으로 확인할 수 있습니다.
Docker Buildx Build –load는 언제 사용하는가?
다음과 같은 상황에서 사용합니다.
- 로컬 테스트
- 개발 환경 이미지 실행
- Docker Compose 테스트
- 빌드 결과 확인
- CI 테스트 환경
특히 개발자가 이미지를 빌드한 후 바로 컨테이너 실행을 확인할 때 유용합니다.
Docker Buildx Build 기본 사용법
기본 예제:
docker buildx build \
--load \
-t my-app:v1 .빌드 완료 후:
docker images확인:
REPOSITORY TAG
my-app v1로컬 이미지로 저장된 것을 확인할 수 있습니다.
Docker Buildx Build –load와 Docker Build 차이
일반 Docker Build:
docker build \
-t app:v1 .결과:
Local Docker Image바로 사용 가능합니다.
하지만 Buildx Build:
docker buildx build \
-t app:v1 .기본 출력 방식에 따라 로컬 저장되지 않을 수 있습니다.
이때:
--load옵션을 추가합니다.
Docker Buildx Build –load 실무 예제
로컬 개발 이미지 생성
명령:
docker buildx build \
--load \
-t development-app:v1 .확인:
docker images실행:
docker run development-app:v1개발 환경에서 바로 테스트할 수 있습니다.
Docker Compose 테스트 활용
개발자가 새로운 이미지를 만들었습니다.
빌드:
docker buildx build \
--load \
-t local-api:test .Docker Compose:
services:
api:
image: local-api:test실행:
docker compose up로컬에서 새 이미지를 테스트할 수 있습니다.
Docker Buildx Build –load와 –push 차이
두 옵션은 저장 위치가 다릅니다.
–load
저장 위치:
Local Docker Engine사용 목적:
- 개발
- 테스트
- 로컬 실행
예:
docker buildx build \
--load \
-t app:v1 .–push
저장 위치:
Docker Registry사용 목적:
- 운영 배포
- Kubernetes
- CI/CD
예:
docker buildx build \
--push \
-t company/app:v1 .정리:
--load = 내 컴퓨터에 저장
--push = 서버 저장소에 업로드Docker Buildx Build –load와 멀티 플랫폼 관계
주의할 점이 있습니다.
--load는 일반적으로 단일 플랫폼 이미지에서 사용합니다.
예:
가능:
docker buildx build \
--platform linux/amd64 \
--load \
-t app:v1 .제한:
docker buildx build \
--platform linux/amd64,linux/arm64 \
--load \
-t app:v1 .멀티 플랫폼 이미지는 하나의 로컬 Docker Engine에 저장하기 어렵기 때문에 일반적으로 사용하지 않습니다.
멀티 플랫폼:
--push사용을 권장합니다.
Docker Buildx Build –load 출력 확인
빌드:
docker buildx build \
--load \
-t test-image:v1 .확인:
docker images test-image결과:
REPOSITORY
test-image
TAG
v1정상적으로 로컬 저장된 것을 확인할 수 있습니다.
Linux 서버 문제 해결
개발 서버에서 이미지를 빌드했습니다.
명령:
docker buildx build \
-t app:test .빌드 성공:
Successfully built하지만 실행:
docker run app:test오류:
Unable to find image원인을 확인했습니다.
docker images결과:
이미지 없음Buildx 결과가 로컬 Docker Engine에 저장되지 않은 상태였습니다.
해결:
docker buildx build \
--load \
-t app:test .확인:
docker images결과:
app:test실행:
docker run app:test정상 실행되었습니다.
Docker Buildx Build –load는 로컬 개발 환경에서 가장 많이 사용하는 옵션입니다.
Docker Buildx Build –load 사용 시 주의사항
첫 번째는 멀티 플랫폼 이미지에는 적합하지 않습니다.
두 번째는 로컬 Docker Engine 공간을 사용합니다.
세 번째는 대용량 이미지는 저장 시간이 오래 걸릴 수 있습니다.
네 번째는 운영 배포 목적이라면 --push를 사용하는 것이 좋습니다.
Best Practice
Docker Buildx Build –load 활용 방법:
- 로컬 테스트는 –load 사용
- 운영 배포는 –push 사용
- 멀티 플랫폼은 Registry Push 사용
- 빌드 후 docker images 확인
- 테스트 완료 후 Registry 업로드
- 개발 환경과 운영 환경을 분리
자주 묻는 질문
Docker Buildx Build –load는 무엇인가요?
Buildx로 생성한 이미지를 로컬 Docker Engine에 저장하는 옵션입니다.
왜 Buildx 이미지는 바로 보이지 않나요?
Buildx는 BuildKit 출력 방식을 사용하기 때문에 기본적으로 로컬 저장을 하지 않을 수 있습니다.
–load와 –push를 같이 사용할 수 있나요?
일반적으로 함께 사용할 수 없습니다.
저장 목적이 다릅니다.
멀티 플랫폼 빌드에서도 사용할 수 있나요?
제한적입니다.
멀티 플랫폼은 보통 --push를 사용합니다.
마무리
Docker Buildx Build –load는 빌드한 이미지를 로컬 환경에서 바로 사용하기 위한 중요한 옵션입니다.
개발 과정에서 Docker 이미지를 테스트하거나 Docker Compose 환경에서 검증할 때 매우 유용하며, docker images와 docker run을 통해 바로 확인할 수 있습니다.
반면 운영 배포나 멀티 플랫폼 이미지는 --push 방식이 적합합니다.
Docker Buildx에서는 목적에 따라 --load와 --push를 구분하여 사용하는 것이 안정적인 이미지 관리 방법입니다.