Docker Pull: registry, autenticazione e risoluzione dei problemi

Il comando docker pull è abbastanza autoesplicativo, ma sotto il cofano succede molto di più di quanto persino gli esperti navigati sappiano.

Ogni sviluppatore dovrebbe saperlo. Scarichi immagini ogni giorno, ma quando qualcosa si rompe è difficile capire il perché. O l'autenticazione fallisce senza un motivo chiaro, o scattano i rate limit, o finisci con la versione sbagliata dell'immagine in produzione. Ogni errore ti ruba tempo per essere risolto, quando non sarebbe dovuto accadere.

Capire davvero come funziona docker pull ti dà controllo. Saprai da dove arrivano le immagini, come scaricarle e come risolvere i problemi prima che arrivino in produzione.

In questo articolo ti spiego come funziona il download delle immagini sotto il cofano, come entrano in gioco i registry e come effettuare i pull sia nello sviluppo locale sia negli ambienti di produzione.

Se sei alle prime armi con Docker, ti consiglio vivamente di seguire il nostro corso Introduction to Docker , che copre le basi necessarie per comprendere questo articolo.

Come funziona docker pull sotto il cofano

In questa sezione vedremo la meccanica del comando docker pull e chiariremo cosa succede dietro le quinte.

Cosa succede durante un docker pull

La sintassi di base è semplice:

docker pull python:3.14.2-bookworm

Questo comando, per impostazione predefinita, comunica con Docker Hub, scarica l'immagine di Python e la memorizza in locale sulla tua macchina. Ma dietro le quinte c'è più di quanto sembri.

Ecco il flusso:

• Il tuo client Docker invia una richiesta al registry (Docker Hub, a meno che non specifichi diversamente)

• Il registry risponde con il manifest dell'immagine, che elenca tutti i layer che compongono l'immagine

• Il client quindi scarica ogni layer che non ha già e li memorizza in /var/lib/docker sui sistemi Linux, e in directory gestite da Docker Desktop (ad esempio, sotto ~Library/Containers/… su macOS e C:\Users\[Username]\AppData\... su Windows.)

Il tag :latest è il valore predefinito di Docker quando non specifichi una versione. Esegui docker pull python senza tag, e otterrai python:latest. Sembra comodo, ma è rischioso. Il tag :latest non significa "la versione stabile più recente". Significa "quello che il maintainer dell'immagine ha etichettato come latest". Questo potrebbe cambiare tra un pull e l'altro, rompendo le tue build senza preavviso.

Layer delle immagini e content-addressable storage

Le immagini Docker sono costruite a partire da layer.

Ogni layer rappresenta una modifica rispetto al precedente. Quando crei un'immagine, ogni istruzione RUN, COPY o ADD nel tuo Dockerfile crea un nuovo layer. L'immagine finale è una pila di questi layer, assemblati in ordine.

Per esempio, guarda i comandi dietro la Python 3.14 image di cui sopra: c'è parecchio in ballo.

Il content-addressable storage è ciò che rende possibile tutto questo. Ogni layer ottiene un hash univoco basato sui suoi contenuti. Se due immagini condividono lo stesso layer di base (come ubuntu:24.04), Docker memorizza quel layer una sola volta. Quando esegui il pull di una nuova immagine che usa la stessa base, Docker salta il download.

Questo riduce banda e storage. Esegui il pull di dieci immagini di Python con tag diversi e Docker riutilizza i layer comuni tra tutte. Scarichi solo ciò che è realmente diverso.

docker pull vs docker image pull

Entrambi i comandi sono funzionalmente identici. Scaricano immagini dai registry e le memorizzano in locale.

La differenza è organizzativa. Docker ha introdotto il gruppo di comandi docker image come parte di una ristrutturazione della CLI per rendere i comandi più intuitivi. Invece di avere docker pull, docker rmi e docker images sparsi, hanno raggruppato i comandi relativi alle immagini sotto docker image pull, docker image rm e docker image ls.

Usa quello che preferisci. docker pull è più corto e più comune nella documentazione. docker image pull è più esplicito e si adatta meglio agli script dove conta la chiarezza. Scegline uno e mantieni lo stile coerente nel tuo team.

Riferimenti alle immagini Docker spiegati

Un riferimento a un'immagine ha fino a cinque parti: HOST/NAMESPACE/REPOSITORY:TAG@DIGEST.

Ecco cosa significa ogni parte:

• HOST: L'indirizzo del registry (es., docker.io, gcr.io, quay.io). Se lo ometti, Docker usa Docker Hub.

• NAMESPACE: Di solito il tuo nome utente o l'organizzazione (es., library per le immagini ufficiali, o mycompany per quelle private).

• REPOSITORY: Il nome effettivo dell'immagine (es., python, nginx, redis).

• TAG: L'identificatore di versione (es., 3.14.2-bookworm, latest). Se lo salti, il valore predefinito è :latest.

• DIGEST: Un hash SHA256 del manifest dell'immagine (es., @sha256:abc123...). Questo è immutabile: i tag possono cambiare, i digest no.

La maggior parte dei pull ha questo aspetto:

docker pull python:3.14.2-bookworm

Questo si espande a docker.io/library/python:3.14.2-bookworm dietro le quinte.

Per registry privati, ti serve il riferimento completo:

docker pull myregistry.example.com/myteam/myimage

Usare riferimenti precisi (tag specifici o digest) mantiene le tue deployment riproducibili. Esegui il pull di python:3.14.2-bookworm oggi e il mese prossimo, e otterrai la stessa immagine. Esegui due volte il pull di python:latest, e con ogni probabilità non sarà così.

Docker registry e da dove arrivano le immagini

I registry sono i luoghi in cui Docker archivia e distribuisce le immagini: sono la fonte per ogni comando docker pull che esegui.

Docker Hub come registry predefinito

Docker Hub è il registry predefinito per tutti i comandi docker pull a meno che tu non specifichi diversamente.

Esegui docker pull python:3.14.2-bookworm, e Docker traduce automaticamente in docker.io/library/python:3.14.2-bookworm. Non devi eseguire l'accesso per le immagini pubbliche: Docker Hub le serve in modo anonimo, anche se con rate limit per gli utenti non autenticati.

Su Docker Hub ci sono due tipi di immagini: immagini ufficiali e immagini della community.

• Immagini ufficiali provengono da publisher verificati e sono mantenute da Docker o dai vendor del software. Vivono sotto il namespace library (che Docker ti nasconde). Quando esegui il pull di python, nginx o redis, stai ottenendo Immagini ufficiali che seguono le best practice di Docker per sicurezza e aggiornamenti regolari.

• Immagini della community sono tutto il resto. Chiunque può pubblicare un'immagine su Docker Hub sotto il proprio username o organizzazione. Se esegui il pull di johndoe/python-custom, stai affidandoti a johndoe per mantenere correttamente quell'immagine. Alcune immagini della community sono ottime e ben mantenute. Altre non vengono aggiornate da anni e contengono vulnerabilità note.

La fiducia qui conta. Le Immagini ufficiali ricevono patch di sicurezza regolari e hanno documentazione chiara. Ma con le immagini della community, sta a te verificare chi le mantiene e se sono sicure da usare.

Registry privati e personalizzati

La maggior parte delle aziende non vuole che le proprie immagini container risiedano sul Docker Hub pubblico.

I registry privati sono la soluzione. Decidi chi può eseguire il pull delle immagini, controlli le policy di retention e mantieni il codice proprietario all'interno della tua infrastruttura. Questo è importante per la conformità, la sicurezza e la gestione degli accessi tra team.

Soluzioni comuni per registry privati includono:

• Harbor: registry open-source con scansione di sicurezza e controllo degli accessi integrati
• JFrog Artifactory: soluzione enterprise che gestisce immagini Docker e altri tipi di artefatti
• Registry cloud: AWS ECR, Google Container Registry (GCR), Azure Container Registry (ACR)

Ovviamente, i riferimenti alle immagini cambiano quando usi un registry personalizzato. Invece di python:3.14.2-bookworm, ora devi specificare il percorso completo:

docker pull myregistry.company.com/team/python:3.14.2-bookworm

L'hostname del registry va per primo, poi il tuo namespace (di solito un team o il nome di un progetto), quindi repository e tag. Docker non userà Docker Hub quando vede un hostname personalizzato: andrà direttamente al tuo registry privato.

Autenticazione, rate limit e controllo degli accessi

L'autenticazione serve sia per push che per pull delle immagini, e diventa particolarmente importante quando incappi nei rate limit o accedi a registry privati.

Accesso e gestione delle credenziali

Puoi usare il comando docker login per autenticarti con un registry:

docker login

Ti verranno richiesti username e password di Docker Hub. Per registry privati, specifica l'hostname:

docker login myregistry.company.com

Docker memorizza localmente le tue credenziali dopo l'accesso. Su Linux, si trovano in ~/.docker/config.json. Su macOS, Docker usa il portachiavi di sistema per una maggiore sicurezza.

Il problema è che il file di config memorizza le credenziali in base64 per impostazione predefinita, che non è crittografia. Chiunque abbia accesso alla tua home directory può decodificarle. Per mitigare, puoi invece usare un credential helper: Docker supporta i portachiavi nativi dei sistemi operativi che archiviano le password in modo sicuro.

Ecco alcune best practice per la gestione delle credenziali:

• Usa i credential helper (docker-credential-osxkeychain, docker-credential-wincred)

• Non fare mai commit di config.json nel controllo di versione

• Usa token di accesso invece delle password quando possibile

• Ruota regolarmente le credenziali, soprattutto per account condivisi

Rate limit di Docker Hub

Docker Hub limita quante immagini puoi scaricare in una finestra temporale.

Gli utenti anonimi (senza login) hanno 100 pull ogni sei ore per indirizzo IP. Gli utenti autenticati con account gratuito hanno 200 pull ogni sei ore. I piani a pagamento hanno limiti più alti o pull illimitati a seconda del livello.

Questi limiti contano quando esegui pipeline CI/CD, scarichi immagini frequentemente durante lo sviluppo o lavori su infrastrutture condivise dove più utenti condividono lo stesso IP. Quando raggiungi il limite, i pull falliranno finché la finestra non si resetta.

Puoi controllare lo stato attuale del tuo rate limit:

TOKEN=$(curl "<https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull>" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" <https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest>

Ecco alcuni modi per aumentare il tuo rate limit (per la maggior parte degli sviluppatori non sarà un problema):

• Autentica i tuoi pull: esegui l'accesso per avere limiti più alti, anche con un account gratuito
• Usa mirror del registry: configura una cache pull-through che memorizza localmente le immagini
• Passa a registry privati: ospita un tuo registry per evitare del tutto i limiti di Docker Hub
• Fai caching locale delle immagini: scarica una volta, riusa molte volte invece di scaricare di continuo

La soluzione più semplice è semplicemente eseguire l'accesso. Solo questo raddoppia il tuo rate limit.

Opzioni avanzate per il pull delle immagini

Queste opzioni avanzate ti danno precisione e controllo, esattamente ciò che serve negli ambienti di produzione.

Scaricare immagini tramite digest

I digest sono identificatori immutabili basati sull'hash del contenuto dell'immagine.

I tag possono cambiare. Qualcuno pubblica una nuova immagine con lo stesso tag e, all'improvviso, python:3.14.2-bookworm punta a contenuti diversi rispetto a ieri. I digest non possono cambiare: sono hash SHA256 del manifest dell'immagine. Lo stesso digest indica sempre esattamente la stessa immagine.

Esegui il pull per digest così:

docker pull python@sha256:6d58c1a9444bc2664f0fa20c43a592fcdb2698eb9a9c32257516538a2746c19a

docker pull --platform linux/amd64 python:3.14.2-bookworm

Questo conta soprattutto in CI/CD e in produzione. Testi contro una specifica immagine, distribuisci esattamente quella. Niente sorprese, niente drift tra ambienti. Se il tuo deployment dipende da una versione specifica, usa il digest, non il tag.

Pull di immagini multi-architettura

Le immagini multi-arch raggruppano versioni per diverse architetture CPU in un unico riferimento.

Esegui il pull di python:3.14.2-bookworm, e Docker seleziona automaticamente la versione giusta per il tuo sistema: amd64 per macchine x86, arm64 per Apple Silicon o server ARM. Il registry serve l'architettura corretta senza che tu debba fare nulla.

Ma a volte ti serve una specifica architettura. Usa il flag --platform:

docker pull --platform linux/amd64 python:3.14.2-bookworm

Questo è utile quando sviluppi su Apple Silicon ma devi testare la versione amd64 che girerà in produzione, o quando costruisci immagini per un'architettura diversa da quella della tua macchina di build.

Scaricare più tag

Il flag --all-tags scarica ogni tag di un repository:

docker pull --all-tags python

Questo scarica tutti i tag di Python: dozzine di versioni, varianti e architetture. Ti ritroverai con gigabyte di immagini.

Non usarlo a meno che non ti serva davvero. La banda costa, lo storage si riempie in fretta e probabilmente non ti servono tutte le versioni di Python mai rilasciate. Scarica invece i tag specifici che usi davvero.

Annullare un pull

Premi Ctrl+C o CMD+C per annullare un pull in corso.

Docker interrompe il download di nuovi layer ma mantiene quelli già completati. La prossima volta che esegui il pull della stessa immagine, riprende da dove era rimasto invece di ricominciare da capo.

È utile quando scarichi per sbaglio l'immagine sbagliata, quando un pull impiega troppo su una connessione lenta o quando ti accorgi che non ti serve davvero quell'immagine in questo momento. Annulla, correggi il comando e rilancia il pull senza sprecare il lavoro già fatto.

Considerazioni sulle prestazioni con docker pull 

Le reti reali hanno vincoli, come limiti di banda, proxy e connessioni lente. Questi possono rallentare i pull delle immagini più del dovuto, quindi vediamo cosa puoi fare.

Ottimizzare le prestazioni del pull

Per impostazione predefinita, Docker scarica i layer dell'immagine in parallelo.

Invece di scaricare i layer uno alla volta, Docker apre più connessioni e scarica diversi layer contemporaneamente. Questo accelera i pull su connessioni veloci, ma non noterai grandi differenze su reti lente dove la banda è il collo di bottiglia.

Due strategie comuni aiutano ancora di più:

• Il caching mantiene le immagini scaricate in locale. Scarica un'immagine una volta, usala centinaia di volte. Docker controlla se hai già i layer prima di scaricare qualsiasi cosa. Se l'immagine non è cambiata, il pull si completa all'istante.
• Il preloading delle immagini significa scaricarle durante le ore di minor traffico o come parte del processo di deploy. I sistemi CI/CD spesso mettono in cache le immagini base sugli agent di build così gli sviluppatori non aspettano i pull ogni volta che eseguono una build. I server di produzione possono scaldare le cache durante il deploy per evitare di scaricare immagini quando arriva il traffico.

Scaricare immagini dietro proxy

Le reti aziendali instradano il traffico attraverso proxy per sicurezza, monitoraggio e controllo degli accessi.

Docker deve conoscere questi proxy per scaricare le immagini. Senza configurazione del proxy, i pull falliscono con timeout di connessione o errori DNS perché Docker prova a raggiungere i registry direttamente invece di passare per il proxy.

Configuri i proxy su due livelli: il client Docker e il demone Docker. Il client (il comando docker) usa automaticamente le impostazioni proxy HTTP del tuo sistema. Il demone richiede una configurazione esplicita in /etc/docker/daemon.json o tramite i file di servizio di systemd.

Risoluzione dei problemi comuni di pull

Ecco una checklist pratica per quando i pull falliscono: succederà, ed è importante sapere cosa controllare per primo.

Errori comuni e come diagnosticarli

Errori di autenticazione si presentano come errori "unauthorized" o "access denied".

Verifica se hai effettuato l'accesso con docker login. Se sì, le credenziali potrebbero essere scadute o errate. Disconnettiti con docker logout, poi ricollegati. Per registry privati, assicurati di usare l'hostname corretto nel comando di login.

Tag mancanti generano errori "manifest unknown" o "not found".

Il tag non esiste. Ricontrolla il nome del tag: gli errori di battitura sono comuni. Controlla l'interfaccia web del registry per vedere quali tag esistono davvero. Ricorda che i tag possono essere eliminati, quindi qualcosa che funzionava ieri oggi potrebbe non esserci più.

Timeout di rete si verificano quando Docker non riesce a raggiungere il registry.

Per prima cosa controlla la connessione a Internet. Poi verifica di poter raggiungere direttamente il registry: esegui ping registry-1.docker.io o curl -I <https://registry-1.docker.io>. Se sei dietro un proxy, assicurati che Docker lo conosca. Se il registry è privato, verifica regole del firewall e connessioni VPN.

I problemi di permessi si presentano come errori "denied" anche quando sei autenticato.

Hai effettuato l'accesso, ma il tuo account non ha i permessi di pull per questo repository specifico. Contatta il proprietario del repository o l'amministratore del registry per ottenere l'accesso. Su Docker Hub, di solito significa che l'immagine è privata e non sei nella lista degli accessi.

Problemi di risoluzione DNS e rete

I fallimenti DNS impediscono a Docker di trovare il server del registry.

Vedrai errori come "no such host" o "temporary failure in name resolution". In pratica Docker non riesce a tradurre l'hostname del registry in un indirizzo IP, quindi non può effettuare la connessione.

Per risolvere, verifica la risoluzione DNS con nslookup registry-1.docker.io o dig registry-1.docker.io. Se questi comandi falliscono, il tuo server DNS è irraggiungibile o mal configurato. Prova a passare temporaneamente a un DNS pubblico come 8.8.8.8 per vedere se si risolve.

Nelle reti aziendali, il server DNS potrebbe risolvere solo host interni. Assicurati che l'hostname del tuo registry privato sia nel server DNS, o aggiungilo a /etc/hosts come workaround finché il DNS non viene sistemato.

docker pull in workflow orchestrati e locali

Passiamo alla parte pratica: come funziona il comando docker pull negli scenari che puoi aspettarti nel tuo lavoro quotidiano.

Pull delle immagini in Kubernetes

Kubernetes scarica automaticamente le immagini quando distribuisci i pod.

Definisci un container nello spec del pod con un riferimento a un'immagine e Kubernetes gestisce il pull per te. Il kubelet su ciascun nodo verifica se l'immagine esiste in locale. In caso contrario, la scarica dal registry prima di avviare il container.

Le pull policy controllano quando Kubernetes scarica le immagini:

• Always: scarica l'immagine ogni volta, anche se esiste in locale

• IfNotPresent: scarica solo se l'immagine non è già presente sul nodo (predefinito per le immagini con tag)

• Never: non scaricare mai, fallisci se l'immagine non è già locale

Imposta la policy nello spec del pod con imagePullPolicy. Usa Always per i tag :latest in sviluppo per ottenere aggiornamenti. Usa IfNotPresent per tag specifici in produzione per evitare pull non necessari.

imagePullSecrets permette a Kubernetes di accedere ai registry privati. Puoi creare un secret con le credenziali del registry e poi referenziarlo nello spec del pod. Senza di esso, Kubernetes può scaricare solo immagini pubbliche.

Docker Compose e sviluppo locale

Compose automatizza i pull quando avvii applicazioni multi-servizio.

Esegui docker compose up e Compose controlla l'immagine di ogni servizio. Se un'immagine manca, Compose la scarica prima di avviare i container. Non devi eseguire docker pull manualmente per ogni servizio: ci pensa Compose.

Funziona alla grande in sviluppo. Puoi definire i servizi in docker-compose.yml, eseguire un solo comando e Compose scarica tutto ciò che ti serve. Il primo up richiede più tempo per il download delle immagini, ma le esecuzioni successive sono istantanee se le immagini non sono cambiate.

docker compose vs docker compose pull

Sono due comandi diversi che fanno cose diverse.

docker compose up avvia i servizi. Scarica automaticamente le immagini mancanti, ma solo se non esistono già in locale. Se hai già python:3.14.2-bookworm sulla tua macchina, Compose la usa senza cercare aggiornamenti.

docker compose pull scarica esplicitamente tutte le immagini definite nel tuo file compose, che esistano o meno in locale. Controlla i registry per aggiornamenti e scarica versioni più recenti, se disponibili.

Ecco quando ti serve docker compose pull:

• Stai usando tag :latest e vuoi la versione più recente. Esegui prima docker compose pull per ottenere gli aggiornamenti, poi docker compose up per partire con immagini fresche.

• Stai facendo debug e sospetti che la tua immagine locale sia obsoleta o corrotta. Scarica copie nuove con docker compose pull, poi riavvia.

• Vuoi precaricare le immagini prima di avviare i servizi. Esegui docker compose pull durante il deploy per mettere in cache le immagini, poi docker compose up partirà istantaneamente senza attendere download.

La differenza chiave è che up scarica solo ciò che manca, mentre pull aggiorna tutto indipendentemente da ciò che hai già.

Conclusione

Il comando docker pull sembra semplice, ma sotto la superficie succede molto e ci sono molte impostazioni che puoi regolare. Ecco alcune best practice da ricordare.

Usa tag espliciti o digest invece di :latest. Autenticati per evitare i rate limit. Fai attenzione a banda e storage quando scarichi immagini, soprattutto nelle pipeline CI/CD dove esegui pull continuamente.

Considera i pull delle immagini come parte della tua pipeline di sicurezza. Ogni pull è un potenziale vettore di attacco se usi fonti non affidabili o immagini obsolete con vulnerabilità note. Verifica le fonti, esegui scansioni e mantieni aggiornate le immagini base.

I registry Docker e gli strumenti cambiano regolarmente. Resta aggiornato con le novità del tuo provider di registry per evitare sorprese che possano interrompere il tuo workflow.

Quando sei pronto a portare le tue competenze su Docker e containerizzazione a un livello professionale, dai un'occhiata al nostro corso Intermediate Docker o scegli il nostro percorso completo Containerization and Virtualization with Docker and Kubernetes .