Déployer Pi-hole avec Docker en 2026 : tutoriel complet (DNS adblock, config réseau, DHCP)

Marre des publicités et des traqueurs sur tous vos appareils — y compris la TV connectée et le smartphone où aucun bloqueur n’est installable ? Pi-hole résout le problème à la racine. C’est un serveur DNS qui bloque les domaines publicitaires et de pistage au niveau du réseau : une fois que vos appareils l’utilisent comme DNS, chaque requête vers un domaine de pub est interceptée et renvoyée dans le vide. Résultat : moins de pubs, moins de traqueurs, des pages qui chargent plus vite, et une visibilité totale sur ce que vos appareils contactent en arrière-plan.

Pi-hole est l’un des services self-hosted les plus rentables en effort/bénéfice : léger, simple, et utile pour toute la maison. Dans ce tutoriel, on le déploie via Docker Compose, on configure le réseau pour que tous vos appareils en profitent, et on aborde l’option serveur DHCP. Particularité du DNS : contrairement à un service web, Pi-hole n’a pas besoin de HTTPS public, mais sa configuration réseau demande quelques précautions qu’on détaille.

Prérequis

Une machine qui reste allumée en permanence sur votre réseau local : Raspberry Pi, mini-PC, NAS ou petit serveur. Pi-hole tient dans 512 Mo de RAM. Beaucoup l’hébergent à la maison, mais on peut aussi le faire tourner sur un VPS chez Scaleway ou OVHcloud couplé à un VPN pour bloquer les pubs en déplacement.
Une IP fixe (statique) pour cette machine sur votre réseau local. C’est indispensable : si l’adresse change, vos appareils perdent leur DNS et n’ont plus Internet.
Docker et Docker Compose installés (commande à l’étape 1).
L’accès à l’administration de votre box/routeur pour changer le serveur DNS distribué au réseau.

Étape 1 : Installer Docker et Docker Compose

Sur Ubuntu/Debian :

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

Déconnectez-vous/reconnectez-vous, puis vérifiez :

docker --version && docker compose version

Étape 2 : Fixer l’IP de la machine et libérer le port 53

Pi-hole écoute sur le port 53 (DNS). Or, sur Ubuntu, ce port est souvent occupé par systemd-resolved, le résolveur DNS local. Il faut le libérer.

Vérifiez d’abord qui écoute sur le port 53 :

sudo ss -tulpn | grep :53

Si systemd-resolved apparaît, désactivez son écoute sur le port 53 sans casser la résolution DNS de la machine :

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo nano /etc/systemd/resolved.conf.d/pihole.conf

[Resolve]
DNSStubListener=no

Faites pointer /etc/resolv.conf vers un fichier géré manuellement pour que la machine elle-même garde une résolution DNS :

sudo rm -f /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
sudo systemctl restart systemd-resolved

Vérifiez que le port 53 est désormais libre :

sudo ss -tulpn | grep :53

Assurez-vous aussi que la machine a une IP statique (configurée via Netplan ou via une réservation DHCP sur votre box). On utilisera 192.168.1.10 comme exemple.

Étape 3 : Le docker-compose.yml de Pi-hole

mkdir -p ~/pihole && cd ~/pihole
nano docker-compose.yml

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: unless-stopped
    # Le port 53 doit être lié sur l'IP de l'hôte pour le réseau local
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      # Interface d'administration web (HTTP en local)
      - "8080:80/tcp"
    environment:
      TZ: "Europe/Paris"
      # Mot de passe de l'interface d'administration (à changer !)
      FTLCONF_webserver_api_password: "remplacez_par_un_mot_de_passe_fort"
      # DNS amont (résolveurs vers lesquels Pi-hole transmet les requêtes légitimes)
      FTLCONF_dns_upstreams: "1.1.1.1;9.9.9.9"
      # IP de cette machine sur le réseau local
      FTLCONF_dns_listeningMode: "all"
    volumes:
      - ./etc-pihole:/etc/pihole
    # Permet à Pi-hole de gérer le DHCP si vous l'activez (étape 7)
    cap_add:
      - NET_ADMIN
    dns:
      - 127.0.0.1
      - 1.1.1.1

Quelques explications. Le port 8080 expose l’interface web (on évite le port 80 pour ne pas entrer en conflit avec un éventuel reverse proxy). FTLCONF_dns_upstreams définit les résolveurs vers lesquels Pi-hole envoie les requêtes non bloquées (ici Cloudflare et Quad9). cap_add: NET_ADMIN n’est nécessaire que si vous activez le DHCP intégré.

Étape 4 : Lancer Pi-hole

cd ~/pihole && docker compose up -d
docker compose logs -f pihole

Quand les logs indiquent que le service FTL est prêt, ouvrez l’interface d’administration : http://192.168.1.10:8080/admin. Connectez-vous avec le mot de passe défini dans FTLCONF_webserver_api_password.

Étape 5 : Tester la résolution DNS

Avant de basculer tout le réseau, vérifiez que Pi-hole répond et bloque bien. Depuis une autre machine du réseau :

# Doit renvoyer une réponse normale (domaine légitime)
dig @192.168.1.10 selfhostr.fr +short

# Doit renvoyer 0.0.0.0 ou une réponse vide (domaine publicitaire bloqué)
dig @192.168.1.10 doubleclick.net +short

Si le premier renvoie une IP et le second 0.0.0.0 (ou rien), Pi-hole fonctionne.

Étape 6 : Faire utiliser Pi-hole par tout le réseau

C’est l’étape qui généralise le blocage. Deux approches.

Méthode recommandée : sur la box/routeur. Connectez-vous à l’administration de votre box et changez le serveur DNS distribué par le DHCP pour qu’il pointe vers l’IP de Pi-hole (192.168.1.10). Tous les appareils qui obtiennent leur configuration réseau de la box utiliseront alors Pi-hole automatiquement. C’est la solution la plus propre.

Beaucoup de box opérateur grand public ne permettent malheureusement pas de changer le DNS distribué. Dans ce cas :

Méthode par appareil. Renseignez manuellement 192.168.1.10 comme DNS dans les paramètres réseau de chaque appareil (ordinateur, téléphone, TV).

Astuce : mettez uniquement l’IP de Pi-hole comme DNS, sans second DNS « de secours » pointant vers la box ou un DNS public — sinon les appareils contourneront Pi-hole dès qu’il sera momentanément indisponible, et le blocage sera incohérent.

Étape 7 (optionnelle) : Pi-hole comme serveur DHCP

Si votre box ne permet pas de changer le DNS distribué, la solution radicale consiste à désactiver le DHCP de la box et à laisser Pi-hole le gérer. Il distribuera alors lui-même les adresses IP et s’imposera comme DNS.

Dans l’administration de votre box, désactivez le serveur DHCP.
Dans Pi-hole, allez dans Settings → DHCP, activez le serveur DHCP, et définissez une plage d’adresses (par exemple 192.168.1.50 à 192.168.1.200) cohérente avec votre réseau, ainsi que la passerelle (l’IP de votre box).

Le cap_add: NET_ADMIN du compose autorise le conteneur à fournir le DHCP. Attention : ne laissez jamais deux serveurs DHCP actifs simultanément sur le même réseau, cela provoque des conflits d’adresses.

Étape 8 : Ajouter des listes de blocage et des exceptions

Pi-hole arrive avec une liste de blocage par défaut, mais vous pouvez en ajouter d’autres dans Lists. Après tout ajout, lancez la mise à jour de gravité :

docker exec pihole pihole -g

Pensez aux listes blanches (allowlist) : certains sites légitimes utilisent des domaines parfois bloqués (paiements, télémétrie utile). Si un service casse, identifiez le domaine fautif dans l’onglet « Query Log » et ajoutez-le en exception plutôt que de désactiver Pi-hole.

Étape 9 : Sécuriser l’interface et sauvegarder

L’interface d’administration de Pi-hole est en HTTP local. Ne l’exposez jamais directement sur Internet. Si vous voulez y accéder à distance, passez par un VPN (WireGuard) ou un reverse proxy HTTPS avec authentification — jamais en clair.

Toute la configuration vit dans ~/pihole/etc-pihole. Sauvegardez ce dossier :

nano ~/pihole/backup.sh

#!/bin/bash
set -euo pipefail
BACKUP_DIR="$HOME/pihole/backups"
STAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

# Export natif de la configuration (Teleporter)
docker exec pihole pihole-FTL --teleporter > "$BACKUP_DIR/pihole-teleporter-$STAMP.zip"

# Conserve 14 jours
find "$BACKUP_DIR" -name 'pihole-teleporter-*.zip' -mtime +14 -delete

chmod +x ~/pihole/backup.sh
(crontab -l 2>/dev/null; echo "0 3 * * * $HOME/pihole/backup.sh") | crontab -

Pour répliquer ces sauvegardes hors-site, voir sauvegarde automatique avec Restic et Backblaze.

Étape 10 : Vérification finale

# Le conteneur tourne
docker ps --filter "name=pihole"

# Pi-hole écoute bien sur le port 53
sudo ss -tulpn | grep :53

# La résolution fonctionne depuis le réseau
dig @192.168.1.10 selfhostr.fr +short

Dans le tableau de bord web, après quelques heures d’usage, vous verrez le pourcentage de requêtes bloquées : c’est la preuve que Pi-hole filtre activement le trafic de tout votre réseau.

Pièges courants et dépannage

« Port 53 already in use » au démarrage. systemd-resolved occupe encore le port. Reprenez l’étape 2 et vérifiez DNSStubListener=no.
Plus d’Internet sur le réseau. Pi-hole est tombé et il était l’unique DNS. Redémarrez le conteneur ; pour éviter cela, fiabilisez la machine (restart: unless-stopped) ou prévoyez une seconde instance.
Les pubs ne sont pas bloquées sur certains appareils. Beaucoup d’appareils (Android, smart TV, IoT) imposent leur propre DNS « en dur » (souvent celui de Google). Bloquez le DNS sortant non autorisé sur votre routeur (redirection forcée vers Pi-hole) ou bloquez le DNS-over-HTTPS connu.
Conflits DHCP. Deux serveurs DHCP actifs. Désactivez celui de la box si vous activez celui de Pi-hole.

FAQ

Pi-hole bloque-t-il les pubs dans les applications et sur les TV ?

Oui, pour tout ce qui passe par des requêtes DNS vers des domaines connus de publicité/pistage. C’est son grand avantage sur une extension navigateur : il protège les smart TV, consoles et téléphones où aucun bloqueur n’est installable. En revanche, il ne bloque pas les pubs servies depuis le même domaine que le contenu (comme YouTube), car couper ce domaine couperait le service lui-même.

Ai-je besoin d’un HTTPS pour Pi-hole ?

Non, pas pour son rôle de DNS, qui est purement local. L’interface d’administration est en HTTP sur le réseau local et ne doit jamais être exposée publiquement. Si vous voulez y accéder de l’extérieur, faites-le via un VPN (WireGuard) plutôt qu’en ouvrant un port.

Que se passe-t-il si la machine Pi-hole tombe en panne ?

Si Pi-hole est l’unique DNS du réseau, plus aucune résolution ne fonctionne : Internet semble coupé. Pour fiabiliser, configurez restart: unless-stopped (déjà fait), hébergez Pi-hole sur une machine stable, ou déployez une seconde instance en DNS secondaire. Évitez en revanche de mettre un DNS public en secondaire, car les appareils contourneraient alors le blocage.

Pi-hole ralentit-il ma connexion ?

Au contraire, il l’accélère souvent. En bloquant les requêtes vers les serveurs de pub et de pistage, les pages chargent moins de ressources inutiles. La résolution DNS elle-même est mise en cache par Pi-hole, ce qui peut même la rendre plus rapide pour les domaines déjà visités.

Dois-je activer le DHCP de Pi-hole ?

Seulement si votre box ne permet pas de changer le DNS distribué au réseau. Dans ce cas, désactiver le DHCP de la box et le confier à Pi-hole est la façon la plus fiable d’imposer Pi-hole à tous les appareils. Si votre box laisse modifier le DNS, gardez son DHCP et changez simplement le DNS : c’est plus simple.

Pi-hole ou AdGuard Home : lequel choisir ?

Les deux bloquent les pubs au niveau DNS et sont d’excellents choix. AdGuard Home intègre nativement le chiffrement DNS (DoH/DoT) et une interface un peu plus moderne ; Pi-hole bénéficie d’une communauté immense et d’innombrables tutoriels. Notre comparatif Pi-hole vs AdGuard Home vous aide à trancher.

🛒 Matériel recommandé

Pour ce projet, voici le matériel que nous conseillons (liens Amazon) :

En tant que Partenaire Amazon, Selfhostr réalise un bénéfice sur les achats remplissant les conditions requises — sans surcoût pour vous.