.nh
.TH "DOCKER" "1" "Aug 2026" "Docker Community" "Docker User Manuals"

.SH "نام (NAME)"
docker-image-pull \- دریافت یا دانلود یک ایمیج از یک رجیستری


.SH "خلاصه دستور (SYNOPSIS)"
\fBdocker image pull [OPTIONS] NAME[:TAG|@DIGEST]\fP


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

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


.SH "مثال‌ها (EXAMPLES)"
.SS "دریافت یک ایمیج از Docker Hub"
برای دانلود یک ایمیج خاص یا مجموعه‌ای از ایمیج‌ها (یعنی یک مخزن)، از
\fBdocker image pull\fR (یا شکل کوتاه \fBdocker pull\fR) استفاده کنید. اگر هیچ تگی ارائه نشود،
موتور Docker Engine به‌طور پیش‌فرض از تگ \fB:latest\fR استفاده می‌کند. این مثال ایمیج
\fBdebian:latest\fR را دریافت می‌کند:

.EX
$ 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
.EE

.PP
ایمیج‌های داکر می‌توانند از چندین لایه تشکیل شوند. در مثال بالا، ایمیج
از یک لایه منفرد تشکیل شده است؛ \fBe756f3fdd6a3\fR\&.

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

.EX
$ 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
.EE

.PP
برای مشاهده اینکه کدام ایمیج‌ها به‌صورت محلی موجود هستند، از دستور
\fBdocker-images(1)\fP استفاده کنید:

.EX
$ docker images

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

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

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

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

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

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

.EX
$ 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
.EE

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

.EX
sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
.EE

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

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

.EX
$ 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
.EE

.PP
دایجست همچنین می‌تواند در دستورالعمل \fBFROM\fR یک Dockerfile استفاده شود، برای مثال:

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

.PP
.RS

.PP
\fBنکته\fP

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

.RE

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

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

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

.PP
اعتبارنامه‌های رجیستری توسط \fBdocker-login(1)\fP مدیریت می‌شوند\&.

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

.SH "دریافت یک مخزن با چندین ایمیج"
به‌طور پیش‌فرض، \fBdocker image pull\fR یک ایمیج \fIمنفرد\fP را از رجیستری دریافت می‌کند. یک مخزن
می‌تواند شامل چندین ایمیج باشد. برای دریافت تمام ایمیج‌ها از یک مخزن، هنگام استفاده از
\fBdocker image pull\fR گزینه \fB-a\fR (یا \fB--all-tags\fR) را ارائه دهید\&.

.PP
این دستور تمام ایمیج‌ها را از مخزن \fBubuntu\fR دریافت می‌کند:

.EX
$ 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
.EE

.PP
پس از اتمام دریافت، از دستور \fBdocker image ls\fR (یا شکل کوتاه \fBdocker images\fR)
برای مشاهده ایمیج‌هایی که دریافت شده‌اند استفاده کنید. مثال زیر تمام ایمیج‌های \fBubuntu\fR
را که به‌صورت محلی موجود هستند نشان می‌دهد:

.EX
$ 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
.EE

.SH "لغو یک عملیات دریافت"
متوقف کردن پروسه \fBdocker image pull\fR، برای مثال با فشردن کلیدهای \fBCTRL-c\fR هنگام اجرا
در ترمینال، عملیات دریافت را خاتمه می‌دهد.

.EX
$ docker image pull ubuntu

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

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


.SH "گزینه‌ها (OPTIONS)"
\fB-a\fP, \fB--all-tags\fP[=false]
	دانلود تمام ایمیج‌های تگ‌گذاری‌شده در مخزن

.PP
\fB--platform\fP=""
	تنظیم پلتفرم اگر سرور توانایی چندپلتفرمی دارد

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


.SH "ببینید (SEE ALSO)"
\fBdocker-image(1)\fP