---
title: "Accéder à un service localhost du Mac depuis un conteneur Docker · Guides Kilobat"
url: "https://kilobat.app/fr/guides/localhost-from-container.html"
description: "Dans un conteneur, localhost désigne le conteneur. Utilisez host.docker.internal pour joindre une base de données, une API ou un serveur de modèles qui tourne sur votre Mac."
---

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.

## Causes probables

- **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.

## Comment vérifier

1. Vérifiez que le service fonctionne sur le Mac. Remplacez 8000 par votre port.

   ```
   curl http://localhost:8000
   ```
2. 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.
3. 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
   ```

## Comment corriger

1. Dans le conteneur, utilisez `host.docker.internal` au lieu de `localhost`. Docker Desktop et OrbStack prennent tous deux en charge ce nom.
2. 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
   ```
3. 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
   ```
4. Si la connexion échoue toujours, examinez les réglages du coupe-feu de macOS. Voir [Le coupe-feu de macOS bloque les connexions entrantes](https://kilobat.app/fr/guides/macos-firewall-incoming.html).

## Avec Kilobat

1. 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
   ```
2. 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
   ```

## Questions

**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

- [Docker Docs : Explore networking how-tos on Docker Desktop](https://docs.docker.com/desktop/features/networking/networking-how-tos/)
- [OrbStack Docs : Container networking](https://docs.orbstack.dev/docker/network)
- [Documentation OrbStack : Host networking](https://docs.orbstack.dev/docker/host-networking)
- lsof(8), page man installée avec macOS 27.2

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.

## Guides associés

- [Impossible d’accéder à un conteneur Docker depuis le Mac](https://kilobat.app/fr/guides/docker-container-from-mac.html): Sur Mac, Docker exécute les conteneurs dans une machine virtuelle Linux.
- [Le coupe-feu de macOS bloque les connexions entrantes](https://kilobat.app/fr/guides/macos-firewall-incoming.html): Le coupe-feu de macOS contrôle les connexions que d’autres ordinateurs ouvrent vers votre Mac.
- [Trouver pourquoi un site ou une API ne se connecte pas](https://kilobat.app/fr/guides/recipes/why-cant-it-connect.html): Quand Internet fonctionne mais qu’une adresse échoue, Kilobat vérifie chaque couche tour à tour.
- [Port déjà utilisé sur un Mac](https://kilobat.app/fr/guides/port-already-in-use.html): Un seul processus peut écouter sur un même port TCP et une même adresse.