docker image pull

docker image pull

레지스트리에서 이미지를 내려받는 명령어예요.

출처: 문서

본문

대부분의 이미지는 Docker Hub 레지스트리의 베이스 이미지 위에 만들어져요. Docker Hub에는 미리 빌드된 이미지가 많아서, 직접 정의하고 구성할 필요 없이 pull 해서 써볼 수 있어요.

특정 이미지나 이미지 집합(리포지토리)을 내려받으려면 docker pull을 쓰세요.

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

항목	내용
Description	레지스트리에서 이미지 내려받기
Aliases	docker pull

프록시 구성

HTTP 프록시 서버 뒤에 있다면(예: 기업 환경), 이미지 pull/push 같은 작업에 프록시 서버를 쓰도록 Docker 데몬을 구성해야 할 수 있어요. 자세한 내용은 dockerd 커맨드라인 참조를 보세요.

동시 다운로드

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

옵션

옵션	기본값	설명
-a, --all-tags		리포지토리의 모든 태그 이미지 내려받기
--platform		API 1.32+ 서버가 다중 플랫폼 지원 시 플랫폼 설정
-q, --quiet		상세 출력 억제

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는 이미지를 다이제스트로 내려받게 해줘요. 다이제스트로 이미지를 내려받을 때는 정확히 어느 버전의 이미지를 내려받을지 지정하는 거예요. 이렇게 하면 이미지를 해당 버전에 "고정(pin)"할 수 있고, 사용하는 이미지가 항상 동일함을 보장할 수 있어요.

이미지의 다이제스트를 알려면 먼저 이미지를 내려받아요. 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는 pull이 끝난 뒤 이미지의 다이제스트를 출력해요. 위 예시에서 이미지의 다이제스트는 다음과 같아요.

sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

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

이미지를 내려받을 때 태그 대신 다이제스트가 대신 쓰여요. 예를 들어 위 이미지를 다이제스트로 내려받으려면 다음 명령을 실행해요.

$ 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]>"

참고

이 기능을 쓰면 이미지를 특정 시점의 버전에 "고정"해요. 따라서 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

pull이 끝난 뒤 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

pull 취소

docker pull 프로세스를 죽이면(예: 터미널에서 실행 중 CTRL-c 누르기), pull 작업이 종료돼요.

$ docker pull ubuntu

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

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

더 알아보기

• 이미지 목록은 docker image ls