Should Immich Use Host Networking or a Bridge Network?
For most Docker-based Immich deployments, a user-defined bridge is the cleaner default; host networking is a targeted workaround, not a universal performance upgrade.
Immich mainly needs reliable client-to-server, server-to-database, server-to-Redis, machine-learning, and reverse-proxy paths. Both network modes can provide them. The choice should be made by reproducing the real failure or access requirement, testing one mode at a time, and keeping the configuration that is easiest to observe and recover.
Start With the Paths Immich Actually Needs
Draw the stack as connections rather than containers: clients reach the public or local Immich endpoint; the proxy reaches the Immich server; the application reaches PostgreSQL and Redis; and the server reaches machine learning. Note which connections stay inside Docker and which cross the host boundary.
A user-defined bridge gives containers their own network namespace while allowing services on the same network to resolve one another by service name. The networking overview from Docker networking modes is useful for this distinction: published ports serve host or external clients, while container DNS handles service-to-service traffic.
If every required path already works on a bridge, host networking has not solved a demonstrated problem. Keep the bridge and document service names, networks, and published ports so a later proxy or Compose change can be checked against a known topology.
Prefer a User-Defined Bridge When Isolation and Stable Service Names Matter
Bridge mode lets Immich services communicate on an explicit application network without exposing every container port on the host. This is especially useful when a reverse proxy shares the network and can target the Immich service name directly, reducing dependence on a container IP that may change after recreation.
The homelab analysis of host networking trade-offs notes that removing Docker NAT is rarely a meaningful performance gain for ordinary homelab web traffic. The more important differences are namespace isolation, port publishing, and how services discover one another.
Bridge mode fails as a design only when a required path cannot be expressed or remains unreliable after the network, DNS, firewall, and proxy membership are corrected. Do not switch modes simply because a client reports โserver unreachableโ; first prove the request is stopping at the Docker boundary.
Use Host Networking Only for a Specific, Reproducible Requirement
Host mode places the container on the host network namespace, which removes Docker port translation and gives the service the host network context. That can simplify certain discovery or unusual routing cases, but it also removes the container-level port boundary and increases the chance of host port collisions.
A current comparison of bridge and host networking frames the choice around performance, isolation, service exposure, and debugging. Apply those dimensions to the Immich path rather than assuming host mode is inherently more reliable.
If host mode fixes one symptom, reproduce the test twice and explain why. For example, confirm that the same hostname, account, proxy, and client fail on the bridge and pass on host while application logs remain otherwise healthy. If the result cannot be repeated, the mode change may only have masked DNS or stale-network state.
Keep the Reverse Proxy on an Explicit, Recoverable Route
A reverse proxy should reach Immich through a stable upstream definition after either container restarts. On a bridge, prefer a shared user-defined network and service-name upstream over a manually copied container IP. On host mode, point the proxy to the intended host address and port while checking for collisions.
The ZimaSpace host-versus-bridge test pattern uses an analogous conditional rule: discovery simplicity can justify host mode, while isolation and explicit proxy integration favor a bridge. Immich has different protocols, so reuse the decision method rather than Plex-specific port assumptions.
Restart the proxy alone, then Immich alone, then the full stack. A passing design restores the same local and remote routes each time without editing IP addresses. A topology that needs manual rewiring after recreation is not stable enough, regardless of whether it uses host or bridge networking.
Choose the Mode That Passes the Same Acceptance Test With Less Risk
Test local web login, mobile-app connection, a small upload, a large upload, reverse-proxy access, service-to-service health, and one full restart. Record latency and failures, but do not over-weight tiny throughput differences if both modes remain far below the network ceiling.
Choose bridge when all functions pass and you benefit from explicit exposure, container DNS, and isolation. Choose host when a required path reproducibly fails on a correctly configured bridge and host mode fixes it without creating port conflicts or widening exposure beyond what you accept.
If both modes fail the same way, stop toggling networking. The cause is more likely in DNS, TLS, proxy headers, authentication, firewalling, storage, or the application itself. Preserve the failing request and logs, return to the simpler known-good topology, and diagnose the next boundary.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
