docker image pull

레지스트리에서 이미지를 다운로드하는 명령이에요. Docker Hub나 자기 호스트 레지스트리에서 이미지를 받아올 때 사용해요. 별칭으로 docker pull을 쓸 수 있어요.

출처: 문서

본문

대부분의 이미지는 Docker Hub 레지스트리의 기본 이미지(base image) 위에 만들어져요.

Docker Hub에는 미리 빌드된 이미지가 많아서, 직접 정의하고 구성하지 않아도 pull해서 사용해볼 수 있어요.

특정 이미지 또는 이미지 집합(즉 저장소)을 다운로드하려면 docker pull을 사용해요.

docker image pull [OPTIONS] NAME[:TAG|@DIGEST]

지원하는 옵션은 다음과 같아요.

옵션	기본값	설명
`-a, --all-tags`		저장소의 모든 태그된 이미지 다운로드
`--platform`		API 1.32+ 서버가 멀티 플랫폼을 지원하면 플랫폼 설정
`-q, --quiet`		상세 출력 억제

프록시 구성

HTTP 프록시 서버 뒤에 있다면(예: 기업 환경), 이미지 풀·푸시 같은 작업에 프록시를 쓰도록 Docker 데몬을 구성해야 할 수 있어요. 자세한 내용은 dockerd 명령줄 참조를 참고해요.

동시 다운로드

기본적으로 Docker 데몬은 이미지의 레이어 세 개를 한 번에 다운로드해요. 대역폭이 낮은 연결이라면 타임아웃 문제가 생길 수 있는데, --max-concurrent-downloads 데몬 옵션으로 낮출 수 있어요. 자세한 내용은 데몬 문서를 참고해요.

Docker Hub에서 이미지 풀

docker image pull(또는 축약형 docker pull)로 특정 이미지 또는 이미지 집합(저장소)을 다운로드해요. 태그를 제공하지 않으면 Docker Engine은 기본값으로 :latest 태그를 사용해요. 이 예제는 debian:latest 이미지를 풀해요.

$ docker image pull debian

Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest

Docker 이미지는 여러 레이어로 구성될 수 있어요. 위 예제에서 이미지는 e756f3fdd6a3 단일 레이어로 이뤄져 있어요.

레이어는 이미지끼리 재사용될 수 있어요. 예를 들어 debian:bookworm 이미지는 debian:latest와 레이어를 공유해요. 따라서 debian:bookworm 이미지를 풀하면 해당 레이어가 이미 로컬에 있으므로 메타데이터만 받고 레이어는 받지 않아요.

$ docker image pull debian:bookworm

bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm

로컬에 어떤 이미지가 있는지 보려면 docker images 명령을 사용해요.

$ docker images

REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
debian       bookworm   4eacea30377a   8 days ago     124MB
debian       latest     4eacea30377a   8 days ago     124MB

Docker는 콘텐츠 주소 지정(content-addressable) 이미지 저장소를 사용하며, 이미지 ID는 이미지의 구성과 레이어를 포함하는 SHA256 다이제스트예요. 위 예제에서 debian:bookworm과 debian:latest는 다른 이름으로 태그된 같은 이미지라서 같은 이미지 ID를 가져요. 같은 이미지이므로 레이어는 한 번만 저장되고 추가 디스크 공간을 차지하지 않아요.

이미지·레이어·콘텐츠 주소 지정 저장소에 대한 자세한 내용은 이미지·컨테이너·스토리지 드라이버 이해를 참고해요.

다이제스트(불변 식별자)로 이미지 풀

지금까지는 이미지 이름(과 "태그")으로 풀했어요. 이름과 태그를 쓰는 건 이미지를 다루기 편리한 방법이에요. 태그를 쓸 때는 docker pull을 다시 실행해서 해당 이미지의 최신 버전을 확보할 수 있어요. 예를 들어 docker pull ubuntu:24.04는 Ubuntu 24.04 이미지의 최신 버전을 풀해요.

어떤 경우에는 이미지가 새 버전으로 업데이트되지 않길 바라고 고정 버전을 쓰고 싶을 수 있어요. Docker는 다이제스트로 이미지를 풀할 수 있게 해줘요. 다이제스트로 풀하면 가져올 이미지 버전을 정확히 지정하는 셈이에요. 이렇게 하면 이미지를 그 버전에 "고정"하고, 사용하는 이미지가 항상 같다는 걸 보장할 수 있어요.

이미지의 다이제스트를 알려면 먼저 이미지를 풀해요. Docker Hub에서 최신 ubuntu:24.04 이미지를 풀어볼게요.

$ docker pull ubuntu:24.04

24.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04

Docker는 풀이 끝나면 이미지의 다이제스트를 출력해요. 위 예제에서 이미지의 다이제스트는:

sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

Docker는 레지스트리에 푸시할 때도 이미지의 다이제스트를 출력해요. 방금 푸시한 이미지 버전에 고정하고 싶을 때 유용해요.

다이제스트는 이미지를 풀할 때 태그를 대신해요. 위 이미지를 다이제스트로 풀하려면:

$ docker pull ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30: Pulling from library/ubuntu
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Image is up to date for ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

Dockerfile의 FROM에도 다이제스트를 쓸 수 있어요.

FROM ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
LABEL org.opencontainers.image.authors="some maintainer <[email protected]>"

Note

이 기능을 쓰면 이미지를 특정 시점의 버전으로 "고정"해요. Docker는 이후 업데이트된 버전(보안 업데이트 포함)을 풀하지 않아요. 업데이트된 이미지를 풀하려면 다이제스트를 그에 맞게 바꿔야 해요.

다른 레지스트리에서 풀

기본적으로 docker pull은 Docker Hub에서 이미지를 풀해요. 풀할 레지스트리 경로를 수동으로 지정할 수도 있어요. 예를 들어 로컬 레지스트리를 설정했다면 그 경로를 지정해 풀할 수 있어요. 레지스트리 경로는 URL과 비슷하지만 프로토콜 지정자(https://)는 포함하지 않아요.

다음 명령은 포트 5000에서 수신하는 로컬 레지스트리(myregistry.local:5000)에서 testing/test-image 이미지를 풀해요.

$ docker image pull myregistry.local:5000/testing/test-image

레지스트리 자격 증명은 docker login이 관리해요.

Docker는 레지스트리가 안전하지 않은 연결로 접근을 허용하지 않는 한 https:// 프로토콜로 레지스트리와 통신해요. 안전하지 않은 레지스트리 섹션을 참고해요.

여러 이미지가 있는 저장소 풀 (-a, --all-tags)

기본적으로 docker pull은 레지스트리에서 단일 이미지를 풀해요. 저장소는 여러 이미지를 담을 수 있어요. 저장소에서 모든 이미지를 풀하려면 docker pull 사용 시 -a(또는 --all-tags) 옵션을 제공해요.

이 명령은 ubuntu 저장소의 모든 이미지를 풀해요.

$ docker image pull --all-tags ubuntu

Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....

Status: Downloaded newer image for ubuntu

풀이 끝난 뒤 docker image ls 명령(또는 축약형 docker images)으로 풀된 이미지를 확인해요. 아래 예제는 로컬에 있는 모든 ubuntu 이미지를 보여줘요.

$ docker image ls --filter reference=ubuntu
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       22.04     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       jammy     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       24.04     35a88802559d   6 weeks ago    78.1MB
ubuntu       latest    35a88802559d   6 weeks ago    78.1MB
ubuntu       noble     35a88802559d   6 weeks ago    78.1MB

풀 취소

터미널에서 실행 중 CTRL-c를 눌러 docker pull 프로세스를 종료하면 풀 작업이 끝나요.

$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C

엔진은 데몬과 풀을 시작한 클라이언트 사이의 연결이 어떤 이유로든 끊기거나, 명령이 수동으로 종료되면 풀 작업을 종료해요.

docker image pull