docker pull : registres, authentification et dépannage

La commande docker pull est assez explicite, mais beaucoup de choses se passent en coulisses — y compris des détails que même des experts chevronnés ignorent.

Chaque développeur devrait connaître ces mécanismes. Vous récupérez des images au quotidien, mais quand quelque chose casse, il est difficile d'en trouver la cause. L'authentification échoue sans raison claire, les limites de taux s'enclenchent, ou vous déployez en production la mauvaise version d'image. Chaque incident vous fait perdre un temps précieux — alors qu'il aurait pu être évité.

Comprendre le fonctionnement réel de docker pull vous redonne la maîtrise. Vous saurez d'où viennent les images, comment les tirer, et comment dépanner les problèmes avant qu'ils n'atteignent la production.

Dans cet article, j'explique le fonctionnement interne du tirage d'images, le rôle des registres, et comment récupérer des images en développement local comme en production.

Si vous débutez totalement avec Docker, je vous recommande vivement de suivre notre cours Introduction to Docker qui couvre les fondamentaux indispensables pour bien suivre cet article.

Comment fonctionne docker pull sous le capot

Dans cette section, je reviens sur la mécanique de la commande docker pull pour lever toute ambiguïté sur ce qui se passe en arrière-plan.

Ce qui se passe pendant un docker pull

La syntaxe de base est simple :

docker pull python:3.14.2-bookworm

Par défaut, cette commande contacte Docker Hub, télécharge l'image Python et la stocke en local sur votre machine. Mais il se passe bien plus de choses qu'il n'y paraît.

Voici le processus :

• Votre client Docker envoie une requête au registre (Docker Hub, sauf indication contraire)

• Le registre répond avec le manifeste de l'image, qui liste toutes les couches qui la composent

• Votre client télécharge ensuite chaque couche qui n'est pas encore présente localement et les stocke dans /var/lib/docker sur les systèmes Linux, et dans des dossiers gérés par Docker Desktop (par exemple sous ~Library/Containers/… sur macOS et C:\Users\[Username]\AppData\... sous Windows.)

Le tag :latest est utilisé par défaut si vous ne précisez pas de version. Exécutez docker pull python sans tag, et vous obtiendrez python:latest. Cela semble pratique, mais c'est risqué. Le tag :latest ne signifie pas « la dernière version stable », mais « ce que le mainteneur a désiré marquer comme latest ». Cela peut changer d'un tirage à l'autre et casser vos builds sans avertissement.

Couches d'image et stockage adressable par contenu

Les images Docker sont construites à partir de couches.

Chaque couche représente une modification par rapport à la précédente. Lors de la construction d'une image, chaque instruction RUN, COPY ou ADD dans votre Dockerfile crée une nouvelle couche. L'image finale est un empilement ordonné de ces couches.

Par exemple, examinez les commandes derrière l'image Python 3.14 ci-dessus : il s'y passe beaucoup de choses.

Le stockage adressable par contenu rend tout cela possible. Chaque couche reçoit un hachage unique basé sur son contenu. Si deux images partagent la même couche de base (comme ubuntu:24.04), Docker ne la stocke qu'une seule fois. Lorsque vous tirez une nouvelle image qui utilise la même base, Docker saute son téléchargement.

Résultat : moins de bande passante et moins d'espace disque. Tirez dix images Python avec des tags différents, et Docker réutilise les couches communes. Vous ne téléchargez que ce qui change vraiment.

docker pull vs docker image pull

Ces deux commandes sont identiques fonctionnellement. Elles récupèrent des images depuis des registres et les stockent en local.

La différence est organisationnelle. Docker a introduit le groupe de commandes docker image lors d'une refonte de la CLI pour les rendre plus intuitives. Au lieu d'avoir docker pull, docker rmi et docker images dispersées, les commandes liées aux images ont été regroupées en docker image pull, docker image rm et docker image ls.

Utilisez celle que vous préférez. docker pull est plus court et plus courant dans la documentation. docker image pull est plus explicite et mieux adapté aux scripts où la clarté prime. Choisissez un style et harmonisez-le au sein de votre équipe.

Références d'image Docker, explications

Une référence d'image comporte jusqu'à cinq parties : HOST/NAMESPACE/REPOSITORY:TAG@DIGEST.

Voici ce que signifie chaque élément :

• HOST : l'adresse du registre (ex. : docker.io, gcr.io, quay.io). Si vous l'omettez, Docker pointe vers Docker Hub.

• NAMESPACE : généralement votre nom d'utilisateur ou votre organisation (ex. : library pour les images officielles, ou mycompany pour les images privées).

• REPOSITORY : le nom de l'image (ex. : python, nginx, redis).

• TAG : l'identifiant de version (ex. : 3.14.2-bookworm, latest). Par défaut, c'est :latest si vous ne le précisez pas.

• DIGEST : un hachage SHA256 du manifeste de l'image (ex. : @sha256:abc123...). C'est immuable : un tag peut changer, pas un digest.

La plupart des tirages ressemblent à ceci :

docker pull python:3.14.2-bookworm

En coulisses, cela se résout en docker.io/library/python:3.14.2-bookworm.

Pour les registres privés, vous avez besoin de la référence complète :

docker pull myregistry.example.com/myteam/myimage

Utiliser des références précises (tags spécifiques ou digests) garantit la reproductibilité. Tirez python:3.14.2-bookworm aujourd'hui et le mois prochain, vous obtiendrez la même image. Tirez python:latest deux fois, vous avez de fortes chances d'obtenir deux contenus différents.

Registres Docker et provenance des images

Les registres sont les entrepôts où Docker stocke et distribue les images : c'est la source de chaque commande docker pull que vous exécutez.

Docker Hub comme registre par défaut

Docker Hub est le registre par défaut pour toutes les commandes docker pull sauf indication contraire.

Exécutez docker pull python:3.14.2-bookworm, et Docker traduit automatiquement en docker.io/library/python:3.14.2-bookworm. Vous n'avez pas besoin de vous connecter pour les images publiques : Docker Hub les sert anonymement, mais avec des limites de taux pour les utilisateurs non authentifiés.

On trouve deux types d'images sur Docker Hub : images officielles et images communautaires.

• Images officielles : publiées par des éditeurs vérifiés et maintenues par Docker ou les éditeurs logiciels eux-mêmes. Elles se trouvent sous l'espace de noms library (caché par Docker). Quand vous tirez python, nginx ou redis, vous obtenez des images officielles conformes aux bonnes pratiques de Docker en termes de sécurité et de mises à jour régulières.

• Images communautaires : tout le reste. N'importe qui peut publier une image sur Docker Hub sous son nom d'utilisateur ou son organisation. En tirant johndoe/python-custom, vous faites confiance à johndoe pour la maintenir correctement. Certaines images communautaires sont excellentes et bien entretenues, d'autres n'ont pas été mises à jour depuis des années et contiennent des vulnérabilités connues.

La confiance est essentielle : les images officielles bénéficient de correctifs de sécurité réguliers et d'une documentation claire. Avec les images communautaires, c'est à vous de vérifier leur maintenance et leur sécurité.

Registres privés et personnalisés

La plupart des entreprises ne souhaitent pas stocker leurs images de conteneurs sur le Docker Hub public.

Les registres privés sont la solution. Vous déterminez qui peut tirer les images, vous contrôlez les politiques de rétention, et vous gardez le code propriétaire dans votre infrastructure. C'est crucial pour la conformité, la sécurité et la gestion des accès entre équipes.

Parmi les solutions courantes :

• Harbor : registre open source avec analyse de sécurité intégrée et contrôle d'accès
• JFrog Artifactory : solution d'entreprise gérant les images Docker et d'autres types d'artefacts
• Registres cloud : AWS ECR, Google Container Registry (GCR), Azure Container Registry (ACR)

Bien sûr, les références d'image changent avec un registre personnalisé. Au lieu de python:3.14.2-bookworm, vous devez spécifier le chemin complet :

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

Le nom d'hôte du registre en premier, puis votre espace de noms (souvent une équipe ou un projet), puis le dépôt et le tag. Quand Docker voit un hôte personnalisé, il n'utilise pas Docker Hub : il contacte directement votre registre privé.

Authentification, limites de taux et contrôle d'accès

L'authentification concerne aussi bien le push que le pull, et devient essentielle dès que vous atteignez des limites de taux ou que vous accédez à des registres privés.

Connexion et gestion des identifiants

Vous pouvez vous authentifier auprès d'un registre avec la commande docker login :

docker login

Vous serez invité à saisir votre nom d'utilisateur et mot de passe Docker Hub. Pour un registre privé, précisez simplement le nom d'hôte :

docker login myregistry.company.com

Docker stocke ensuite vos identifiants en local. Sous Linux, dans ~/.docker/config.json. Sous macOS, Docker utilise le trousseau système pour davantage de sécurité.

Problème : par défaut, ce fichier encode les identifiants en base64, ce qui n'est pas du chiffrement. Toute personne ayant accès à votre répertoire personnel peut les décoder. Pour mitiger, utilisez un gestionnaire d'identifiants : Docker prend en charge les trousseaux natifs des OS pour stocker les mots de passe de manière sûre.

Quelques bonnes pratiques :

• Utiliser des gestionnaires d'identifiants (docker-credential-osxkeychain, docker-credential-wincred)

• Ne jamais versionner config.json

• Utiliser des jetons d'accès plutôt que des mots de passe quand c'est possible

• Faire tourner régulièrement les identifiants, surtout pour les comptes partagés

Limites de taux de Docker Hub

Docker Hub limite le nombre d'images que vous pouvez tirer sur une période donnée.

Les utilisateurs anonymes (sans connexion) ont droit à 100 tirages par six heures et par adresse IP. Les utilisateurs authentifiés en offre gratuite ont 200 tirages par six heures. Les offres payantes augmentent ces limites, voire les suppriment selon le palier.

Ces limites comptent pour les pipelines CI/CD, les développements fréquents, ou les infrastructures partagées où plusieurs utilisateurs partagent la même IP. Une fois la limite atteinte, vos tirages échouent jusqu'au réarmement de la fenêtre.

Vous pouvez vérifier votre statut courant :

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>

Voici des moyens d'augmenter votre plafond (la plupart des développeurs ne seront pas concernés) :

• Authentifier vos tirages : connectez-vous pour doubler votre limite, même avec un compte gratuit
• Utiliser des miroirs de registre : mettez en place un cache à la demande qui conserve les images en local
• Passer à des registres privés : hébergez votre propre registre pour éviter totalement les limites de Docker Hub
• Mettre en cache localement : tirez une fois, réutilisez autant de fois que nécessaire au lieu de retélécharger

La solution la plus simple consiste à vous connecter. Rien que cela double votre limite.

Options avancées de tirage d'images

Ces options avancées offrent précision et contrôle — exactement ce qu'il faut en production.

Tirer des images par digest

Les digests sont des identifiants immuables basés sur le hachage du contenu de l'image.

Les tags peuvent changer. Quelqu'un pousse une nouvelle image avec le même tag et, soudain, python:3.14.2-bookworm pointe vers un contenu différent de la veille. Les digests, eux, ne changent pas : ce sont des hachages SHA256 du manifeste. Un même digest correspond toujours à exactement la même image.

Tirez par digest comme ceci :

docker pull python@sha256:6d58c1a9444bc2664f0fa20c43a592fcdb2698eb9a9c32257516538a2746c19a

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

C'est essentiel en CI/CD et en production. Vous testez une image précise, vous déployez exactement la même. Pas de surprises, pas d'écarts entre environnements. Si votre déploiement dépend d'une version spécifique, utilisez le digest — pas le tag.

Tirages multi-architectures

Les images multi-arch regroupent dans une même référence les variantes pour différentes architectures CPU.

Tirez python:3.14.2-bookworm, et Docker choisit automatiquement la bonne variante pour votre système : amd64 pour les machines x86, arm64 pour Apple Silicon ou les serveurs ARM. Le registre sert l'architecture adéquate sans intervention de votre part.

Mais il arrive que vous ayez besoin d'une architecture spécifique. Utilisez l'option --platform :

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

Pratique si vous développez sur Apple Silicon mais devez tester la version amd64 qui tournera en production, ou si vous construisez des images pour une architecture différente de celle de votre machine de build.

Tirer plusieurs tags

L'option --all-tags tire tous les tags d'un dépôt :

docker pull --all-tags python

Cela télécharge tous les tags Python : des dizaines de versions, variantes et architectures. Vous cumulerez des gigaoctets d'images.

N'utilisez cette option que si vous en avez vraiment besoin. La bande passante a un coût, le stockage se remplit vite, et vous n'avez probablement pas besoin de toutes les versions de Python jamais publiées. Privilégiez les tags que vous utilisez réellement.

Annuler un tirage

Appuyez sur Ctrl+C ou CMD+C pour annuler un tirage en cours.

Docker arrête de télécharger de nouvelles couches mais conserve celles déjà terminées. Au prochain tirage de la même image, il reprendra où il s'est arrêté au lieu de repartir de zéro.

Pratique si vous avez lancé par erreur le mauvais tirage, si la connexion est trop lente, ou si vous n'avez finalement pas besoin de l'image tout de suite. Annulez, corrigez la commande, puis tirez à nouveau sans gaspiller le travail déjà effectué.

Considérations de performance avec docker pull 

Les réseaux réels ont des contraintes : bande passante limitée, proxys, connexions lentes. Cela peut rallonger les tirages d'images. Voici comment y remédier.

Optimiser les performances de tirage

Docker télécharge par défaut les couches en parallèle.

Au lieu de traiter les couches séquentiellement, Docker ouvre plusieurs connexions et en télécharge plusieurs à la fois. Cela accélère les tirages sur les lignes rapides, mais apporte peu sur les réseaux lents où la bande passante reste le goulot d'étranglement.

Deux stratégies efficaces complémentaires :

• Le cache conserve en local les images tirées. Tirez une image une fois, utilisez-la des centaines de fois. Docker vérifie vos couches locales avant tout téléchargement. Si rien n'a changé, le tirage est quasi instantané.
• Le préchargement consiste à tirer les images en heures creuses ou dans votre processus de déploiement. Les systèmes CI/CD mettent souvent en cache les images de base sur les agents pour éviter d'attendre à chaque build. Les serveurs de production peuvent également « chauffer » le cache lors du déploiement.

Tirer des images derrière un proxy

Dans les réseaux d'entreprise, le trafic transite par des proxys pour des raisons de sécurité, de supervision et de contrôle d'accès.

Docker doit connaître ces proxys pour pouvoir tirer des images. Sans configuration, les tirages échouent par timeout ou erreurs DNS, car Docker tente d'atteindre directement les registres au lieu de passer par le proxy.

La configuration se fait à deux niveaux : le client Docker et le démon Docker. Le client (votre commande docker) utilise automatiquement les paramètres proxy du système. Le démon requiert une configuration explicite dans /etc/docker/daemon.json ou via les fichiers de service systemd.

Dépanner les problèmes de tirage courants

Voici une check-list pratique pour les échecs de tirage — car ils arriveront, et il faut savoir quoi vérifier en premier.

Erreurs fréquentes et diagnostic

Erreurs d'authentification affichées comme « unauthorized » ou « access denied ».

Vérifiez si vous êtes connecté avec docker login. Si oui, vos identifiants sont peut-être expirés ou erronés. Déconnectez-vous avec docker logout, puis reconnectez-vous. Pour les registres privés, assurez-vous d'utiliser le bon nom d'hôte dans la commande de connexion.

Tags manquants se manifestant par « manifest unknown » ou « not found ».

Le tag n'existe pas. Revérifiez l'orthographe ; les fautes de frappe sont fréquentes. Consultez l'interface web du registre pour voir les tags disponibles. Souvenez-vous que des tags peuvent être supprimés : ce qui fonctionnait hier peut ne plus être accessible aujourd'hui.

Délais d'attente réseau quand Docker ne peut pas joindre le registre.

Vérifiez d'abord votre connexion Internet. Puis testez l'accès direct au registre : ping registry-1.docker.io ou curl -I <https://registry-1.docker.io>. Si vous êtes derrière un proxy, assurez-vous que Docker est configuré pour l'utiliser. Pour un registre privé, vérifiez les règles de pare-feu et la connexion VPN.

Les problèmes de droits se manifestent par des « denied » même si vous êtes authentifié.

Vous êtes connecté, mais votre compte n'a pas l'autorisation de tirage pour ce dépôt. Contactez le propriétaire du dépôt ou l'administrateur du registre. Sur Docker Hub, il s'agit généralement d'une image privée à laquelle vous n'avez pas été ajouté.

Problèmes de résolution DNS et réseau

Les échecs DNS empêchent Docker de trouver le serveur du registre.

Vous verrez des erreurs comme « no such host » ou « temporary failure in name resolution ». Concrètement, Docker ne parvient pas à traduire le nom d'hôte du registre en adresse IP, donc la connexion échoue.

Pour résoudre, testez la résolution avec nslookup registry-1.docker.io ou dig registry-1.docker.io. Si ces commandes échouent, votre serveur DNS est injoignable ou mal configuré. Essayez temporairement un DNS public comme 8.8.8.8 pour confirmer.

En entreprise, le DNS peut ne résoudre que des noms internes. Assurez-vous que le nom d'hôte de votre registre privé est déclaré, ou ajoutez-le à /etc/hosts comme solution temporaire.

docker pull dans des workflows orchestrés et locaux

Passons maintenant au concret : comment docker pull se comporte dans les scénarios que vous rencontrez au quotidien.

Tirages d'images dans Kubernetes

Kubernetes tire automatiquement les images au déploiement des pods.

Vous renseignez une référence d'image dans le spec du pod, et Kubernetes gère le tirage. Le kubelet de chaque nœud vérifie la présence locale de l'image. Sinon, il la tire du registre avant de démarrer le conteneur.

Des politiques contrôlent quand tirer :

• Always : toujours tirer, même si l'image est présente localement

• IfNotPresent : ne tirer que si l'image n'est pas déjà sur le nœud (valeur par défaut pour les images taguées)

• Never : ne jamais tirer, échouer si l'image n'est pas déjà locale

Définissez la politique via imagePullPolicy. Utilisez Always avec :latest en développement pour récupérer les mises à jour. Privilégiez IfNotPresent avec des tags spécifiques en production pour éviter les tirages inutiles.

imagePullSecrets permet à Kubernetes d'accéder à des registres privés. Créez un secret avec vos identifiants de registre, puis référencez-le dans le spec du pod. Sans cela, Kubernetes ne peut tirer que des images publiques.

Docker Compose et développement local

Compose automatise les tirages au démarrage d'applications multi-services.

Lancez docker compose up, et Compose vérifie l'image de chaque service. Si une image manque, il la tire avant de démarrer les conteneurs. Inutile d'exécuter docker pull pour chaque service : Compose s'en charge.

C'est idéal en développement. Définissez vos services dans docker-compose.yml, lancez une commande, et Compose tire tout le nécessaire. Le premier up est plus long (téléchargements), les suivants sont instantanés si les images n'ont pas changé.

docker compose vs docker compose pull

Deux commandes différentes pour des usages différents.

docker compose up démarre vos services. Il tire automatiquement les images manquantes, mais uniquement si elles n'existent pas déjà en local. Si vous avez déjà python:3.14.2-bookworm, Compose l'utilise sans vérifier les mises à jour.

docker compose pull tire explicitement toutes les images définies dans votre fichier compose, qu'elles existent localement ou non. Il vérifie les mises à jour sur les registres et télécharge les versions plus récentes si disponibles.

Quand utiliser docker compose pull :

• Vous utilisez des tags :latest et voulez la dernière version. Exécutez docker compose pull pour récupérer les mises à jour, puis docker compose up pour démarrer avec des images à jour.

• Vous déboguez et suspectez une image locale obsolète ou corrompue. Tirez des copies neuves avec docker compose pull, puis redémarrez.

• Vous voulez précharger les images avant de démarrer les services. Exécutez docker compose pull pendant le déploiement pour mettre en cache les images, puis docker compose up démarre instantanément.

La différence clé : up ne tire que ce qui manque, tandis que pull met tout à jour indépendamment de votre cache local.

Conclusion

La commande docker pull paraît simple, mais il se passe beaucoup de choses sous la surface et vous pouvez la paramétrer finement. Voici quelques bonnes pratiques à retenir.

Préférez des tags explicites ou des digests plutôt que :latest. Authentifiez vos tirages pour éviter les limites de taux. Soyez attentif à la bande passante et au stockage, surtout en CI/CD où les tirages sont fréquents.

Considérez les tirages comme une étape de votre chaîne de sécurité. Chaque tirage est un vecteur potentiel d'attaque si vous utilisez des sources non fiables ou des images obsolètes avec des vulnérabilités connues. Vérifiez les sources, scannez les images et gardez vos bases à jour.

Les registres et les outils évoluent régulièrement. Restez informé des mises à jour de votre fournisseur pour éviter les mauvaises surprises.

Quand vous serez prêt à passer au niveau professionnel sur Docker et la conteneurisation, découvrez notre cours Intermediate Docker ou suivez notre parcours Containerization and Virtualization with Docker and Kubernetes.