Développeurs

Un conteneur ne peut pas joindre localhost sur le Mac

Chaque conteneur a sa propre pile réseau. Dans un conteneur, localhost désigne le conteneur lui-même, pas le Mac.

S’applique à : Docker Desktop et OrbStack sur les versions actuelles de macOS.Vérifié le 29 octobre 2026

Symptômes

Une app dans un conteneur obtient « connection refused » sur localhost:5432 ou un port similaire.
La même URL fonctionne dans Safari ou dans Terminal sur le Mac.
Un serveur de modèles ou une API sur le Mac est injoignable depuis un conteneur de développement.

localhost désigne le conteneur. Le conteneur cherche le service dans sa propre pile réseau, où rien n’écoute.
L’adresse de l’hôte change. La documentation de Docker indique que l’adresse IP de l’hôte change. Elle fournit à la place un nom spécial pour l’hôte.
Un coupe-feu sur le Mac. Le coupe-feu de macOS ou une autre app de coupe-feu peut bloquer les connexions entrantes vers le service.

Vérifiez que le service fonctionne sur le Mac. Remplacez 8000 par votre port.
```
curl http://localhost:8000
```
Voyez sur quelle adresse écoute le service du Mac.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
Résultat *:8000 signifie toutes les adresses. 127.0.0.1:8000 signifie l’adresse de bouclage uniquement.
Testez le nom d’hôte depuis l’intérieur du conteneur, si l’image inclut wget.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

Dans le conteneur, utilisez host.docker.internal au lieu de localhost. Docker Desktop et OrbStack prennent tous deux en charge ce nom.
Définissez l’adresse dans la configuration de l’app, par exemple dans une variable d’environnement.
```
docker run -e API_URL=http://host.docker.internal:8000 my-image
```
Avec OrbStack, vous pouvez plutôt utiliser le réseau de l’hôte. Les services du Mac sont alors sur localhost dans le conteneur.
```
docker run --net host my-image
```
Si la connexion échoue toujours, examinez les réglages du coupe-feu de macOS. Voir Le coupe-feu de macOS bloque les connexions entrantes.

Les vérifications de Kilobat s’exécutent sur le Mac, pas dans le conteneur. Ajoutez --context container pour obtenir une commande à lancer dans le conteneur.
```
kilobat why http://localhost:8000 --context container
```
Si un service hébergé appelle votre Mac, utilisez --context provider. Kilobat indique alors que localhost est privé et hors de sa portée.
```
kilobat why http://localhost:8000 --context provider
```

host.docker.internal fonctionne-t-il aussi sous Linux ?

Cette page concerne le Mac. Sur Docker Desktop pour Mac et OrbStack, ce nom renvoie à l’hôte.

Pourquoi Safari atteint-il le service alors que le conteneur n’y arrive pas ?

Safari tourne sur le Mac, donc localhost est le Mac. Le conteneur a son propre localhost.

Sources vérifiées le 29 octobre 2026. Les pages man sont celles installées avec macOS ; ouvrez-en une avec man <name> dans Terminal.