開発者向け
コンテナからMacのlocalhostに接続できない
コンテナにはそれぞれ独自のネットワークスタックがあります。コンテナ内のlocalhostはMacではなく、コンテナ自身を指します。
症状
- コンテナ内のアプリが
localhost:5432などのポートで「connection refused」になる。 - 同じURLが、MacのSafariやターミナルでは使える。
- Mac上のモデルサーバやAPIに、開発用コンテナから接続できない。
考えられる原因
- localhostがコンテナを指している。コンテナは自身のネットワークスタック内でサービスを探しますが、そこでは何も待ち受けていません。
- ホストのアドレスが変わる。Dockerのドキュメントによると、ホストのIPアドレスは変わります。代わりに、ホストを指す特別な名前が用意されています。
- Mac上のファイアウォール。macOSのファイアウォールや他のファイアウォールアプリが、サービスへの受信接続をブロックすることがあります。
確認方法
Mac上でサービスが動いていることを確認します。8000は使っているポートに置き換えてください。
curl http://localhost:8000Macのサービスがどのアドレスで待ち受けているかを確認します。
lsof -nP -iTCP:8000 -sTCP:LISTEN出力
*:8000はすべてのアドレス、127.0.0.1:8000はループバックアドレスのみを意味します。イメージにwgetが含まれていれば、コンテナ内からホスト名をテストします。
docker exec my-container wget -qO- http://host.docker.internal:8000
解決方法
コンテナ内では、
localhostの代わりにhost.docker.internalを使います。Docker DesktopとOrbStackはどちらもこの名前に対応しています。アプリの設定で、環境変数などにこのアドレスを指定します。
docker run -e API_URL=http://host.docker.internal:8000 my-imageOrbStackでは、代わりにホストネットワークを使うこともできます。その場合、コンテナ内の
localhostでMacのサービスに接続できます。docker run --net host my-imageそれでも接続できない場合は、macOSのファイアウォール設定を確認してください。macOSのファイアウォールが受信接続をブロックするを参照してください。
Kilobatを使う場合
Kilobatのチェックはコンテナ内ではなく、Mac上で実行されます。
--context containerを付けると、コンテナ内で実行するコマンドが表示されます。kilobat why http://localhost:8000 --context containerホストされたサービスからMacを呼び出す場合は
--context providerを使います。すると、localhostはプライベートなのでそのサービスからは届かない、とKilobatが伝えます。kilobat why http://localhost:8000 --context provider
よくある質問
host.docker.internalはLinuxでも使えますか？
このページはMacを対象としています。Docker Desktop for MacとOrbStackでは、この名前はホストに解決されます。
コンテナからは接続できないのに、Safariからは接続できるのはなぜですか？
SafariはMac上で動くので、localhostはMacを指します。コンテナには独自のlocalhostがあります。
出典
- Docker Docs：Explore networking how-tos on Docker Desktop
- OrbStack Docs：Container networking
- OrbStackドキュメント：ホストネットワーク
- lsof(8)、macOS 27.2に付属のmanページ
出典は2026年10月29日に確認しました。manページはmacOSに付属のものです。「ターミナル」でman <name>を実行すると開けます。