docker pull

説明

レジストリからイメージやリポジトリを 取得(pull) します。

使い方

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

補足説明

大部分のイメージは、 Docker Hub レジストリにある ベース・イメージ(base image) を元に作られています。

Docker Hub には多くの構築済みのイメージがあります。自分で定義や設定をしなくても、イメージを pull (取得)して試せます。

特定のイメージやイメージの集まり(例:リポジトリ)をダウンロードするには、 docker pull を使います。

プロキシ設定

企業内における設定など HTTP プロキシ・サーバの背後で使う場合には、レジストリに接続する前に、Docker デーモンの設定が必要になるでしょう。設定には環境変数 HTTP_PROXYHTTPS_PROXYNO_PROXY です。これらの環境変数を systemd 上で使う場合には、 systemd で Docker の管理と設定 の環境変数についてをご覧ください。

並列ダウンロード

デフォルトの Docker デーモンは、同時に3つのイメージレイヤを取得します。ネットワーク帯域幅が狭くてタイムアウトを引き起こす場合は、デーモンのオプション --max-concurrent-downloads によって、この数を減らせます。詳細は デーモンのドキュメント をご覧ください。

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

オプション

名前, 省略形 デフォルト 説明
--all-tags , -a   レポジトリにあるタグ付きイメージを全てダウンロード
--disable-content-trust true イメージ検証を省略
--platform   【API 1.32+】サーバがマルチプラットフォーム対応であればプラットフォームを指定
--quiet , -q   冗長な出力をしない

使用例

イメージを Docker Hub から 取得(pull)

特定のイメージやイメージ群(例:リポジトリ)をダウンロードするには、 docker pull を使います。タグを指定しなければ、 Docker Engine はデフォルトで :latest タグを使います。次のコマンドは debian:latest イメージを取得します。

$ docker pull debian

Using default tag: latest
latest: Pulling from library/debian
fdd5d7827f33: Pull complete
a3ed95caeb02: Pull complete
Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa
Status: Downloaded newer image for debian:latest

Docker イメージは複数のレイヤ(層)で構成されています。上の例では、イメージを構成するのは fdd5d7827f33a3ed95caeb02 という2つのレイヤです。

レイヤはイメージ間で再利用できます。例えば、 debian:jessie イメージは debian:latest とレイヤを共有しています。そのため、 debian:jessie イメージの取得時は、レイヤをダウンロードせずにメタデータのみ取得します。なぜなら全てのレイヤがローカルにダウンロード済みだからです。

$ docker pull debian:jessie

jessie: Pulling from library/debian
fdd5d7827f33: Already exists
a3ed95caeb02: Already exists
Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e
Status: Downloaded newer image for debian:jessie

どのようなイメージがローカルにあるかを確認するには docker images コマンドを使います。

$ docker images

REPOSITORY   TAG      IMAGE ID        CREATED      SIZE
debian       jessie   f50f9524513f    5 days ago   125.1 MB
debian       latest   f50f9524513f    5 days ago   125.1 MB

Docker は Content-addressable イメージ・ストアを使います(訳者注:コンテンツに紐付く情報、Docker ではリポジトリ名とタグで、イメージ情報を取得できる保管場所)。そして、イメージ ID とはイメージの設定とレイヤを扱う SHA256 ダイジェストです。先ほどの例では debian:jessiedebian:latest は同じイメージ ID を持っています。イメージ名は違いますが、実際には同じイメージに対してタグ付けしています。どちらも同じイメージのため、レイヤのためのデータを保存するのは1度だけであり、余分なディスク容量は不要です。

イメージ、レイヤ、コンテント・アドレッサブル・ストアに関する詳しい情報は、 /storage/storagedriver をご覧ください。

ダイジェスト( 変わらない識別子(immutable identifier) )でイメージを取得

ここまではイメージを名前(または「タグ」)で取得しました。イメージを扱うのに名前とタグの指定は便利です。イメージに対して docker pull を実行する時にタグを指定したら、そのイメージの最新バージョンをダウンロードします。例えば docker pull ubuntu:14.04 は Ubuntu 14.04 イメージの最新バージョンを取得します。

イメージを最新バージョンではなく、特定のバージョンに固定したい場合があるでしょう。そのような場合、Docker はダイジェスト( digest 値)を指定してイメージを取得できます。ダイジェストを指定してイメージを取得しようとしたら、指定したバージョンのイメージを確実にダウンロードします。したらイメージのバージョンを「固定」し、常に同じイメージの使用を保証します。

イメージのダイジェスト値を知るには、まずイメージを取得します。Docker Hub から最新の ubuntu:20.04 イメージをダウンロードしましょう。

$ docker pull ubuntu:20.04

20.04: Pulling from library/ubuntu
16ec32c2132b: Pull complete
Digest: sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3
Status: Downloaded newer image for ubuntu:20.04
docker.io/library/ubuntu:20.04

Docker はダウンロードが完了したら、イメージのダイジェスト値を表示します。先ほどの例では、イメージのダイジェスト値とは、こちらです。

sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3

Docker はイメージを送信( push )する時のダイジェスト値を表示します。イメージを送信時のバージョンを固定したい場合に役立つでしょう。

イメージの取得時にダイジェスト値を使うには、タグとして扱います。例えば、イメージをダイジェスト値で取得するには、次のコマンドを実行します。

$ docker pull ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3

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

Digest は Dockerfile の FROM でも指定可能です。以下は例です。

FROM ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"

注釈

この機能はイメージに対するバージョンを都度「固定」します。そのため Docker はイメージのバージョンを更新しないため、セキュリティの更新もしません。更新版のイメージを取得したい場合は、適時ダイジェスト値を変更する必要があります。

別のレジストリから取得

docker pull のイメージは Docker Hub から取得するのがデフォルトです。取得するレジストリの場所は、手動で指定可能です。例えば、ローカルにレジストリをセットアップしておけば、そちらを指定してイメージを取得できます。レジストリのパスは URL と似ていますが、プロトコル指示子( https:// )がありません。

以下のコマンドは、ポート 5000 を開いているローカルのレジストリ( myregistry.local:5000 )から testing/test-image イメージを取得するコマンドです。

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

レジストリの認証情報は docker login で管理します。

Docker はレジストリとの通信に https プロトコルを使います。ただし、レジストリが安全ではない接続(insecure connection)を許可している場合は除外します。詳細は をご覧ください。

リポジトリから複数のイメージを取得

デフォルトでは、 docker pull はレジストリから単一のイメージを取得します。リポジトリには複数のイメージがあります。リポジトリから全てのイメージを取得するには docker pull-a (あるいは --all-tags )オプションを使います。

次のコマンドは fedora リポジトリから全てのイメージを取得します。

$ docker pull --all-tags fedora

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

Status: Downloaded newer image for fedora

取得が終わったら、取得した全てのイメージを確認するために docker images コマンドを使います。次の例はローカルに現在ある全ての fedora イメージを表示しています。

$ docker images fedora

REPOSITORY   TAG         IMAGE ID        CREATED      SIZE
fedora       rawhide     ad57ef8d78d7    5 days ago   359.3 MB
fedora       20          105182bb5e8b    5 days ago   372.7 MB
fedora       heisenbug   105182bb5e8b    5 days ago   372.7 MB
fedora       latest      105182bb5e8b    5 days ago   372.7 MB

取得を中止

docker pull プロセスを停止するには、ターミナルで実行中に CTRL-c を押すと、pull 処理を中断します。

$ docker pull fedora

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

注釈

技術的に Engine を停止する処理とは、 Docker Engine デーモンと起点となった Docker Engine クライアント間における取得(pull)に対してです。何らかの理由によって Engine デーモンとの通信を切断した場合も、同様に取得処理が中断します。

親コマンド

コマンド 説明
docker Docker CLI の基本コマンド