docker pull

読む時間の目安: 3 分

説明

レジストリからイメージまたはリポジトリを取得します。

利用方法

$ docker pull [オプション] NAME[:TAG|@DIGEST]

追加説明

たいていのイメージは Docker Hub レジストリから取得したイメージを最上位のベースイメージとして生成されています。

Docker Hub にはあらかじめビルドされた数多くのイメージがあり、何も定義したり設定したりせず、ただpullするだけで利用することができます。

特定のイメージあるいはイメージのセット（つまりリポジトリ）をダウンロードするにはdocker pullを利用します。

プロキシー設定

たとえば会社の設定として HTTP プロキシーサーバーを介している場合、レジストリへの接続を開始する前に、デーモンのプロキシー設定を行う必要があるかもしれません。 その場合は環境変数HTTP_PROXY、HTTPS_PROXY、NO_PROXYを用います。 systemdを利用するホスト上においてこのような変数を設定するには、control and configure Docker with systemd を参考にして変数設定を行ってください。

並列ダウンロード

Docker デーモンはデフォルトにおいて、イメージからプルを行うレイヤー数は、一度に 3 つまでです。 低帯域幅の接続を行っている場合には、タイムアウトの原因となることがあります。 そのような場合にはデーモンオプション--max-concurrent-downloadsを通じて、その数を減らすことができます。 詳しくは デーモンのドキュメント を参照してください。

本コマンドの利用例については、以下に示す 利用例の節 を参照してください。

オプション

利用例

Docker Hub からのイメージのプル

特定のイメージあるいはイメージのセット（つまりリポジトリ）をダウンロードするには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 イメージは複数レイヤーにより構成することができます。 上の例におけるイメージは 2 つのレイヤー、つまりfdd5d7827f33とa3ed95caeb02から構成されています。

レイヤーはイメージによって再利用されます。 たとえばdebian:jessieイメージは、debian:latestイメージの 2 つのレイヤーを共有しています。 したがって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 image store）を利用します。 そこでのイメージ ID は、イメージ設定とレイヤーから算出される SHA256 ダイジェスト値です。 上の例においてdebian:jessieとdebian:latestは、まったく同一のイメージ ID を持っています。 タグ名が異なるだけで、実際には 同一の イメージであるからです。 同一のイメージであることから、レイヤーが保存されるのは 1 度だけであって、別のディスク容量を消費することはありません。

イメージ、レイヤー、イメージストアに関する詳細は イメージ、コンテナー、ストレージドライバーの理解 を参照してください。

不変の識別子であるダイジェスト値によるイメージのプル

ここまでイメージのプルには、イメージ名（とそのタグ名）を用いてきました。 イメージを取り扱う際には、イメージ名とタグ名を使うのが簡単な方法です。 タグを利用すればdocker pullによってイメージをプルする際に、イメージの最新バージョンを取得することができます。 たとえばdocker pull ubuntu:20.04を実行すると Ubuntu 20.04 イメージの最新バージョンが取得できます。

場合によっては、最新バージョンにアップデートする必要がなく、イメージの特定バージョンを利用したいときがあります。 イメージプルの際には ダイジェスト値 を使うことができます。 ダイジェスト値を使ってイメージをプルするということは、プルするイメージがどれであるかを 正確に 指定することになります。 これを行うと特定バージョンを「ねらい打ち」することができ、取り扱うイメージを常に同一のものとすることができます。

イメージのダイジェスト値を知るには、まずはイメージをプルします。 そこで 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

プルが完了するとイメージのダイジェスト値が表示されます。 上の例におけるイメージのダイジェスト値は以下のものです。

sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3

レジストリへの プッシュ を行う際にもこのダイジェスト値は表示されます。 プッシュしたばかりのイメージバージョンを特定したいときに便利です。

イメージをプルする際には、タグの代わりにダイジェスト値を用いることができます。 たとえば上のイメージをダイジェスト値によってプルするには、以下のコマンドを実行します。

$ 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

ダイジェスト値は Dockerfile 内のFROM命令においても利用可能です。 たとえば以下です。

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

メモ

この機能を利用すると、忘れずにイメージのバージョンを特定することができます。 したがってイメージの最新バージョンにはセキュリティアップデートが含まれているかもしれませんが、これを取得しません。 更新されたイメージをプルするのであれば、それに合わせてダイジェスト値を書き換える必要があります。

別レジストリからのプル

docker pullはデフォルトで Docker Hub からイメージをプルします。 プルを行うレジストリは、そのパスを手動で指定することもできます。 たとえばローカルにレジストリを作り出している場合、そこからプルするようにパス指定ができます。 レジストリへのパスは URL に似ていますが、プロトコルの識別子（https://）を含みません。

以下のコマンドは、ローカルレジストリがポート 5000 番で待ち受けているものとして、そこからtesting/test-imageイメージをプルするものです。

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

レジストリの資格情報は docker login を用いて管理されます。

Docker ではhttps://プロトコルを使ったレジストリとのやりとりを行ないますが、ただしセキュアではない接続を許容しているレジストリの場合、それはできません。 詳しくは セキュアでないレジストリ の節を参照してください。

レジストリからの複数イメージのプル

docker pullはデフォルトでは、レジストリから 1 つの イメージをプルします。 リポジトリには多くのイメージがあります。 そこでリポジトリから全イメージをプルするには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を押下してプロセスを kill した場合、プル処理は停止します。

$ docker pull fedora

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

メモ

Docker Engine がプル処理を停止させるのは、Docker Engine デーモンとプル停止を指示したクライアントとの接続が失われたときです。 手動操作以外の別の理由によって Docker Engine デーモンとの接続が失われた場合も、同様にプル処理は停止します。

上位コマンド