nerdctl : CLI compatible Docker pour containerd

nerdctl est une CLI pour containerd qui offre une compatibilité complète avec les commandes Docker. Vous pouvez exécuter des conteneurs, construire des images et utiliser Compose sans Docker — tout en bénéficiant de fonctionnalités avancées comme le lazy pulling, le chiffrement d’images et les checkpoints.

Ce guide couvre l’installation de nerdctl v2.2, les commandes essentielles testées, la gestion des réseaux et volumes, ainsi que les fonctionnalités avancées v2.x. Prérequis : containerd installé et fonctionnel.

Version actuelle

Ce guide utilise nerdctl v2.2.1 (décembre 2025). Nouveautés v2.x : checkpoints conteneurs, manifests multi-arch, healthchecks avec systemd timers, support mount manager (erofs).

Ce que vous allez apprendre

• Installer nerdctl sur Linux (binaire ou bundle complet)
• Utiliser les commandes de base : run, ps, logs, exec, inspect
• Gérer réseaux et volumes personnalisés
• Utiliser Compose pour les applications multi-conteneurs
• Exploiter les fonctionnalités v2.x : checkpoint, manifest, stats

Pourquoi choisir nerdctl plutôt que Docker ?

Critère	Docker	nerdctl
Daemon	dockerd obligatoire	containerd uniquement
Licence	Docker Desktop payant (entreprises)	100% open source (Apache 2.0)
Lazy pulling	Non natif	Stargz, Nydus, OverlayBD, SOCI
Images chiffrées	Non	ocicrypt intégré
Distribution P2P	Non	IPFS natif
Checkpoints	Expérimental	Support CRIU stable
Mode rootless	Complexe	bypass4netns optimisé

Glissez pour voir

nerdctl n’est pas un fork de Docker — c’est un outil natif pour containerd qui reprend la syntaxe Docker pour faciliter l’adoption.

Installation

nerdctl propose deux méthodes d’installation : le binaire seul (si containerd est déjà installé) ou le bundle complet (containerd + BuildKit + CNI plugins inclus).

Binaire seul

Cette méthode suppose que containerd est déjà installé et fonctionnel.

1. Télécharger la dernière version

   VERSION="2.2.1"
   wget https://github.com/containerd/nerdctl/releases/download/v${VERSION}/nerdctl-${VERSION}-linux-amd64.tar.gz

2. Installer le binaire

   sudo tar -xvf nerdctl-${VERSION}-linux-amd64.tar.gz -C /usr/local/bin
   sudo chmod +x /usr/local/bin/nerdctl

3. Vérifier l’installation

   nerdctl --version

   Résultat attendu :

   nerdctl version 2.2.1

Bundle complet

Le bundle nerdctl-full inclut containerd, runc, CNI plugins et BuildKit — idéal pour une installation complète.

1. Télécharger le bundle

   VERSION="2.2.1"
   wget https://github.com/containerd/nerdctl/releases/download/v${VERSION}/nerdctl-full-${VERSION}-linux-amd64.tar.gz

2. Extraire dans /usr/local

   sudo tar -xvf nerdctl-full-${VERSION}-linux-amd64.tar.gz -C /usr/local

3. Activer et démarrer containerd

   sudo systemctl enable --now containerd
   sudo systemctl enable --now buildkit

4. Vérifier l’installation

   nerdctl --version
   containerd --version

Contenu du bundle v2.2.1

• containerd v2.2.1
• runc v1.4.0
• CNI plugins v1.9.0
• BuildKit v0.26.3
• Stargz snapshotter v0.16.3

Vérifier la configuration

Après l’installation, vérifiez que nerdctl communique correctement avec containerd :

sudo nerdctl info

Résultat attendu :

Client:
 Namespace:     default
 Debug Mode:    false

Server:
 Server Version: v2.2.1
 Storage Driver: overlayfs
 Cgroup Driver: systemd
 Cgroup Version: 2
 Kernel Version: 6.8.0-100-generic
 Operating System: Ubuntu 24.04.2 LTS
 CPUs: 16
 Total Memory: 46.83GiB

Permission denied ?

Si vous obtenez une erreur de permission, exécutez nerdctl avec sudo ou configurez le mode rootless (voir section avancée).

Commandes essentielles

nerdctl reprend la syntaxe Docker. Voici les commandes de base testées avec sorties réelles.

Exécuter un conteneur

# Conteneur éphémère (--rm)
sudo nerdctl run --rm alpine:3.19 cat /etc/os-release

Résultat :

NAME="Alpine Linux"
VERSION_ID=3.19.9
PRETTY_NAME="Alpine Linux v3.19"
HOME_URL="https://alpinelinux.org/"

Lancer un conteneur en arrière-plan

# Nginx sur le port 8080
sudo nerdctl run -d --name mon-nginx -p 8080:80 nginx:alpine

Résultat :

234f3562467bd41fe58d0ece451bb2ff479d25fb9c4e740e513a38a58cd2c3e2

Lister les conteneurs

sudo nerdctl ps

Résultat :

CONTAINER ID    IMAGE                             COMMAND                   CREATED          STATUS    PORTS                   NAMES
234f3562467b    docker.io/library/nginx:alpine    "/docker-entrypoint.…"    5 minutes ago    Up        0.0.0.0:8080->80/tcp    mon-nginx

Ajoutez -a pour voir aussi les conteneurs arrêtés.

Consulter les logs

sudo nerdctl logs mon-nginx | tail -5

Résultat :

2026/02/13 07:10:47 [notice] 1#1: nginx/1.29.5
2026/02/13 07:10:47 [notice] 1#1: built by gcc 15.2.0 (Alpine 15.2.0)
2026/02/13 07:10:47 [notice] 1#1: OS: Linux 6.8.0-100-generic
2026/02/13 07:10:47 [notice] 1#1: start worker processes
/docker-entrypoint.sh: Configuration complete; ready for start up

Exécuter une commande dans un conteneur

sudo nerdctl exec mon-nginx cat /etc/nginx/nginx.conf | head -10

Résultat :

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;

events {
    worker_connections  1024;
}

Inspecter un conteneur

sudo nerdctl inspect mon-nginx --format '{{.State.Status}} - {{.NetworkSettings.IPAddress}}'

Résultat :

running - 10.4.0.3

Arrêter et supprimer un conteneur

sudo nerdctl stop mon-nginx
sudo nerdctl rm mon-nginx

Statistiques en temps réel

sudo nerdctl stats --no-stream

Résultat :

CONTAINER ID   NAME           CPU %     MEM USAGE / LIMIT     MEM %     NET I/O         BLOCK I/O     PIDS
234f3562467b   mon-nginx      0.00%     12.85MiB / 46.83GiB   0.03%     1.45kB / 822B   0B / 20.5kB   17

Voir les processus d’un conteneur

sudo nerdctl top mon-nginx

Résultat :

UID      PID      PPID     CMD
root     3777377  3777339  nginx: master process nginx -g daemon off;
message+ 3777625  3777377  nginx: worker process

Gestion des images

Télécharger une image

sudo nerdctl pull alpine:3.19

Lister les images

sudo nerdctl images

Résultat :

REPOSITORY    TAG       IMAGE ID        CREATED           PLATFORM       SIZE         BLOB SIZE
alpine        3.19      6baf43584bcb    2 weeks ago       linux/amd64    8.081MB      3.421MB
nginx         alpine    b76de378d572    2 weeks ago       linux/amd64    47.01MB      18.08MB

Supprimer une image

sudo nerdctl rmi alpine:3.19

Construire une image (nécessite BuildKit)

# Créer un Dockerfile simple
cat > /tmp/Dockerfile << 'EOF'
FROM alpine:3.19
RUN apk add --no-cache curl
CMD ["echo", "Hello from nerdctl!"]
EOF

# Construire l'image
sudo nerdctl build -t mon-image:v1 /tmp

Prérequis BuildKit

La commande nerdctl build nécessite BuildKit. Installez le bundle complet ou installez BuildKit séparément :

sudo systemctl enable --now buildkit

Gestion des réseaux

Créer un réseau personnalisé

sudo nerdctl network create mon-reseau --subnet 172.28.0.0/24

Résultat :

b047bfb73f50a1a7ff26f4264e82dd94d43096fa70c48a1bdf5b67cf4188ab52

Lister les réseaux

sudo nerdctl network ls

Résultat :

NETWORK ID      NAME              FILE
                containerd-net    /etc/cni/net.d/10-containerd-net.conflist
b047bfb73f50    mon-reseau        /etc/cni/net.d/default/nerdctl-mon-reseau.conflist
17f29b073143    bridge            /etc/cni/net.d/nerdctl-bridge.conflist
                host
                none

Connecter un conteneur à un réseau

sudo nerdctl run -d --name app --network mon-reseau nginx:alpine

Supprimer un réseau

sudo nerdctl network rm mon-reseau

Gestion des volumes

Créer un volume

sudo nerdctl volume create mes-donnees

Lister les volumes

sudo nerdctl volume ls

Résultat :

VOLUME NAME     DIRECTORY
mes-donnees     /var/lib/nerdctl/1935db59/volumes/default/mes-donnees/_data

Utiliser un volume

sudo nerdctl run -d --name db -v mes-donnees:/data redis:alpine

Supprimer un volume

sudo nerdctl volume rm mes-donnees

Utilisation de Compose

nerdctl intègre une compatibilité native avec Docker Compose. Pas besoin d’installer docker-compose.

Créer un fichier compose.yaml

compose.yaml

services:
  web:
    image: nginx:alpine
    ports:
      - "8889:80"
  redis:
    image: redis:alpine

Démarrer l’application

sudo nerdctl compose up -d

Résultat :

INFO[0000] Creating network myapp_default
INFO[0000] Ensuring image redis:alpine
INFO[0005] Ensuring image nginx:alpine
INFO[0005] Creating container myapp-redis-1
INFO[0005] Creating container myapp-web-1

Voir l’état des services

sudo nerdctl compose ps

Résultat :

NAME              IMAGE                             COMMAND                   SERVICE    STATUS     PORTS
myapp-web-1       docker.io/library/nginx:alpine    "/docker-entrypoint.…"    web        running    0.0.0.0:8889->80/tcp
myapp-redis-1     docker.io/library/redis:alpine    "docker-entrypoint.s…"    redis      running

Arrêter et supprimer

# Arrêter les services
sudo nerdctl compose down

# Avec suppression des volumes
sudo nerdctl compose down -v

Fonctionnalité v2.1.4

nerdctl compose supporte dockerfile_inline pour définir un Dockerfile directement dans le compose.yaml :

services:
  app:
    build:
      dockerfile_inline: |
        FROM alpine:3.19
        RUN apk add --no-cache curl

Fonctionnalités avancées v2.x

Checkpoints de conteneurs (v2.2)

Les checkpoints permettent de sauvegarder l’état d’un conteneur en cours d’exécution pour le restaurer plus tard. Utile pour la migration ou le debugging.

# Créer un checkpoint
sudo nerdctl checkpoint create mon-conteneur checkpoint-1

# Lister les checkpoints
sudo nerdctl checkpoint ls mon-conteneur

# Supprimer un checkpoint
sudo nerdctl checkpoint rm mon-conteneur checkpoint-1

Prérequis CRIU

Les checkpoints nécessitent CRIU (Checkpoint/Restore In Userspace) :

sudo apt install criu

Gestion des manifests multi-arch (v2.1.4)

Créez et gérez des images multi-architecture :

# Créer un manifest
sudo nerdctl manifest create mon-image:latest \
  mon-image:amd64 \
  mon-image:arm64

# Inspecter un manifest
sudo nerdctl manifest inspect mon-image:latest

# Pousser vers un registre
sudo nerdctl manifest push mon-image:latest

# Supprimer un manifest local
sudo nerdctl manifest rm mon-image:latest

Export et import de conteneurs (v2.1.4)

# Exporter un conteneur vers une archive
sudo nerdctl container export mon-conteneur > conteneur.tar

# Importer comme image
sudo nerdctl image import conteneur.tar mon-image:imported

Mode rootless

Exécutez des conteneurs sans privilèges root pour une sécurité renforcée.

1. Installer les prérequis

   sudo apt install uidmap rootlesskit

2. Configurer containerd en mode rootless

   containerd-rootless-setuptool.sh install

3. Utiliser nerdctl sans sudo

   nerdctl run --rm alpine:3.19 echo "Hello rootless!"

Optimisation réseau

Installez bypass4netns pour améliorer les performances réseau en mode rootless :

containerd-rootless-setuptool.sh install-bypass4netnsd

Lazy pulling (téléchargement différé)

Le lazy pulling permet de démarrer un conteneur avant que l’image soit entièrement téléchargée. Idéal pour les images volumineuses.

Snaphotters supportés :

• Stargz : format eStargz optimisé
• Nydus : accélérateur d’images cloud-native
• OverlayBD : couche block-device
• SOCI : Seekable OCI (Amazon)

# Utiliser le snapshotter stargz
sudo nerdctl --snapshotter stargz run ghcr.io/stargz-containers/nginx:1.23-esgz

Distribution d’images via IPFS

Partagez des images en peer-to-peer sans registre central :

# Pousser une image vers IPFS
sudo nerdctl push ipfs://mon-image:latest

# Exécuter depuis IPFS
sudo nerdctl run ipfs://<CID>

Signature d’images avec Cosign

Signez et vérifiez vos images pour garantir leur intégrité :

# Signer lors du push
sudo nerdctl push --sign=cosign mon-registre/mon-image:latest

# Vérifier lors du pull
sudo nerdctl pull --verify=cosign mon-registre/mon-image:latest

Voir le guide Cosign pour la configuration complète.

Dépannage

Problème	Cause probable	Solution
permission denied	Pas les droits root	Utiliser sudo ou configurer rootless
failed to ping buildkitd	BuildKit non démarré	sudo systemctl start buildkit
network not found	Réseau supprimé ou inexistant	nerdctl network ls puis recréer
image not found	Image non présente localement	nerdctl pull image:tag
container already exists	Nom de conteneur déjà utilisé	nerdctl rm nom ou choisir un autre nom
cgroup driver mismatch	containerd/kubelet mal configurés	Aligner les drivers cgroup

Glissez pour voir

Commandes de diagnostic

# Vérifier l'état de containerd
sudo systemctl status containerd

# Voir les logs containerd
sudo journalctl -u containerd -f

# Vérifier la configuration nerdctl
sudo nerdctl info

# Nettoyer les ressources inutilisées
sudo nerdctl system prune -a

Bonnes pratiques

Sécurité

• Privilégiez le mode rootless pour les environnements de développement
• Signez vos images avec Cosign avant de les déployer
• Limitez les capacités avec --cap-drop=ALL --cap-add=<nécessaire>
• Utilisez des images chiffrées pour les données sensibles

Organisation

• Nommez vos conteneurs avec --name pour faciliter la gestion
• Utilisez des réseaux personnalisés pour isoler les applications
• Préférez les volumes nommés aux bind mounts pour les données persistantes
• Tagguez vos images avec des versions précises (pas latest)

Performance

• Activez le lazy pulling pour les grandes images
• Utilisez le cache BuildKit pour accélérer les builds
• Configurez les limites de ressources avec --memory et --cpus

À retenir

1. nerdctl remplace Docker CLI avec une compatibilité complète et zéro dépendance à dockerd
2. Syntaxe identique : nerdctl run, nerdctl build, nerdctl compose fonctionnent comme Docker
3. Fonctionnalités avancées : lazy pulling, chiffrement, IPFS, checkpoints non disponibles dans Docker
4. Mode rootless : sécurité renforcée avec bypass4netns pour les performances
5. Compose intégré : pas besoin d’installer docker-compose séparément
6. Bundle complet : nerdctl-full inclut containerd, runc, BuildKit et CNI plugins
7. Checkpoints v2.2 : sauvegardez et restaurez l’état des conteneurs avec CRIU
8. Manifests multi-arch : créez des images pour plusieurs architectures facilement

Prochaines étapes

containerd Comprendre le runtime utilisé par nerdctl

BuildKit Construire des images optimisées

Cosign Signer et vérifier vos images

Kubernetes et containerd Utiliser containerd comme runtime Kubernetes

Ressources

• GitHub : containerd/nerdctl
• Documentation : nerdctl docs
• Releases : nerdctl releases
• Stargz snapshotter : containerd/stargz-snapshotter

×

📖 Voir la documentation →