DOCKER(1) Docker User Manuals DOCKER(1)

docker-image-pull - دریافت یا دانلود یک ایمیج از یک رجیستری

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

این دستور یک ایمیج یا یک مخزن را از یک رجیستری دریافت (pull) می‌کند. اگر بیش از یک ایمیج برای یک مخزن وجود داشته باشد (به عنوان مثال fedora)، آن‌گاه تمام ایمیج‌های مربوط به نام آن مخزن به همراه همه تگ‌ها قابل دریافت هستند (گزینه -a یا --all-tags را ببینید).

اگر یک REGISTRY_HOST مشخص نکنید، این دستور به‌طور پیش‌فرض از رجیستری عمومی داکر مستقر در registry-1.docker.io استفاده می‌کند.

برای دانلود یک ایمیج خاص یا مجموعه‌ای از ایمیج‌ها (یعنی یک مخزن)، از 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

ایمیج‌های داکر می‌توانند از چندین لایه تشکیل شوند. در مثال بالا، ایمیج از یک لایه منفرد تشکیل شده است؛ e756f3fdd6a3.

لایه‌ها می‌توانند توسط ایمیج‌ها مجدداً استفاده شوند. به عنوان مثال، ایمیج debian:bookworm لایه خود را با debian:latest به اشتراک می‌گذارد. بنابراین دریافت ایمیج debian:bookworm تنها فراداده (metadata) آن را دریافت می‌کند و لایه‌های آن را دریافت نمی‌کند، زیرا لایه از قبل به‌طور محلی وجود دارد:

$ 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(1) استفاده کنید:

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

داکر از یک مخزن ایمیج آدرس‌پذیر بر اساس محتوا (content-addressable) استفاده می‌کند و شناسه ایمیج (image ID) یک دایجست (digest) هش SHA256 است که پیکربندی و لایه‌های ایمیج را پوشش می‌دهد. در مثال بالا، debian:bookworm و debian:latest شناسه ایمیج یکسانی دارند زیرا آن‌ها همان ایمیج هستند که با نام‌های متفاوتی تگ‌گذاری شده‌اند. از آنجا که هر دو یک ایمیج یکسان هستند، لایه‌های آن‌ها تنها یک بار ذخیره می‌شوند و فضای دیسک اضافی مصرف نمی‌کنند.

برای اطلاعات بیشتر درباره ایمیج‌ها، لایه‌ها و مخزن آدرس‌پذیر بر اساس محتوا، به بخش درک ایمیج‌ها، کانتینرها و درایورهای ذخیره‌سازی ⟨https://docs.docker.com/storage/storagedriver⟩ در مستندات آنلاین مراجعه کنید.

تاکنون، ایمیج‌ها را بر اساس نام (و «تگ») آن‌ها دریافت کرده‌اید. استفاده از نام‌ها و تگ‌ها روشی مناسب برای کار با ایمیج‌ها است. هنگام استفاده از تگ‌ها، می‌توانید مجدداً دستور docker image pull را برای یک ایمیج اجرا کنید تا مطمئن شوید که به‌روزترین نسخه آن ایمیج را در اختیار دارید. برای مثال، docker image pull ubuntu:24.04 آخرین نسخه از ایمیج Ubuntu 24.04 را دریافت می‌کند.

در برخی موارد مایل نیستید ایمیج‌ها به نسخه‌های جدیدتر به‌روزرسانی شوند، بلکه ترجیح می‌دهید از یک نسخه ثابت از یک ایمیج استفاده کنید. داکر این امکان را به شما می‌دهد که یک ایمیج را بر اساس digest (دایجست) آن دریافت کنید. هنگام دریافت یک ایمیج بر اساس دایجست، شما دقیقاً مشخص می‌کنید کدام نسخه از یک ایمیج دریافت شود. انجام این کار به شما اجازه می‌دهد یک ایمیج را به آن نسخه «پین» (pin) کنید و تضمین نمایید ایمیجی که استفاده می‌کنید همیشه یکسان است.

برای آگاهی از دایجست یک ایمیج، ابتدا ایمیج را دریافت کنید. بیایید آخرین ایمیج ubuntu:24.04 را از Docker Hub دریافت کنیم:

$ docker image 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

داکر پس از پایان دریافت، دایجست ایمیج را چاپ می‌کند. در مثال بالا، دایجست ایمیج به این صورت است:

sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

داکر همچنین هنگام ارسال (pushing) به یک رجیستری، دایجست ایمیج را چاپ می‌کند. این مورد ممکن است زمانی که می‌خواهید به نسخه‌ای از ایمیجی که تازه ارسال کرده‌اید پین کنید مفید باشد.

هنگام دریافت یک ایمیج، دایجست جایگزین تگ می‌شود؛ به عنوان مثال برای دریافت ایمیج فوق بر اساس دایجست، دستور زیر را اجرا کنید:

$ docker image 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

دایجست همچنین می‌تواند در دستورالعمل FROM یک Dockerfile استفاده شود، برای مثال:

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

نکته

استفاده از این ویژگی یک ایمیج را به یک نسخه مشخص در طول زمان «پین» می‌کند. بنابراین داکر نسخه‌های به‌روزشده یک ایمیج را که ممکن است شامل به‌روزرسانی‌های امنیتی باشند دریافت نخواهد کرد. اگر می‌خواهید یک ایمیج به‌روزشده را دریافت کنید، باید دایجست را متناسب با آن تغییر دهید.

به‌طور پیش‌فرض، دستور docker image pull ایمیج‌ها را از Docker Hub دریافت می‌کند. همچنین امکان مشخص کردن دستی مسیر یک رجیستری برای دریافت از آن وجود دارد. به عنوان مثال اگر یک رجیستری محلی راه‌اندازی کرده‌اید، می‌توانید مسیر آن را برای دریافت از آن مشخص کنید. مسیر رجیستری مشابه یک نشانی وب (URL) است، اما شامل تعیین‌کننده پروتکل (https://) نمی‌شود.

دستور زیر ایمیج testing/test-image را از یک رجیستری محلی در حال گوش دادن روی درگاه ۵۰۰۰ (myregistry.local:5000) دریافت می‌کند:

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

اعتبارنامه‌های رجیستری توسط docker-login(1) مدیریت می‌شوند.

داکر برای ارتباط با یک رجیستری از پروتکل https:// استفاده می‌کند، مگر اینکه رجیستری اجازه دسترسی از طریق یک اتصال ناامن را داشته باشد. برای اطلاعات بیشتر به بخش رجیستری‌های ناامن ⟨https://docs.docker.com/engine/reference/commandline/dockerd/#insecure-registries⟩ در مستندات آنلاین مراجعه کنید.

به‌طور پیش‌فرض، docker image pull یک ایمیج منفرد را از رجیستری دریافت می‌کند. یک مخزن می‌تواند شامل چندین ایمیج باشد. برای دریافت تمام ایمیج‌ها از یک مخزن، هنگام استفاده از docker image 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

متوقف کردن پروسه docker image pull، برای مثال با فشردن کلیدهای CTRL-c هنگام اجرا در ترمینال، عملیات دریافت را خاتمه می‌دهد.

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

موتور داکر عملیات دریافت را هنگامی که اتصال بین دیمن Docker Engine و کلاینت Docker Engine شروع‌کننده دریافت قطع شود، خاتمه می‌دهد. اگر اتصال به دیمن موتور به دلایلی غیر از تعامل دستی قطع شود نیز عملیات دریافت لغو می‌شود.

-a, --all-tags[=false] دانلود تمام ایمیج‌های تگ‌گذاری‌شده در مخزن

--platform="" تنظیم پلتفرم اگر سرور توانایی چندپلتفرمی دارد

-q, --quiet[=false] جلوگیری از نمایش خروجی‌های پرحجم (verbose)

docker-image(1)

Aug 2026 Docker Community