Skip to content
Blog

Overriding DNS Servers in Docker with `--dns`, `--dns-search`, and `--dns-option`

Override container resolvers with --dns, --dns-search, and --dns-option, plus daemon.json and Compose equivalents, and see how they interact with embedded DNS.

Published on • November 19, 2026

AI Assistant

Resolving registry.internal from a container fails, while the host resolves it fine. That gap has exactly three usual causes: the container never got your corporate resolvers, it got them but has no search domain for the short name, or the embedded DNS server is forwarding somewhere you did not expect. All three are fixed with DNS flags — but only if you know which layer owns the setting.

Three layers, three places to configure

Docker lets you set container DNS at the per-container level, the daemon level, and the Compose level. Names differ slightly between them, so this is the cheat sheet:

LayerServersSearch domainsResolver options
docker run / docker create--dns (repeatable)--dns-search (repeatable)--dns-option (repeatable)
dockerd / daemon.json--dns / "dns"--dns-search / "dns-search"--dns-opt / "dns-opts"
Compose servicedns:dns_search:dns_opt:

Note the traps: the daemon flag is --dns-opt while the container flag is --dns-option (check with docker run --help if in doubt), and the Compose field is dns_opt, not dns_options. Everything in that table maps onto /etc/resolv.conf inside the container, which is also where you verify it:

docker run -d --name api \
  --dns 10.10.0.53 --dns 10.10.0.54 \
  --dns-search corp.example.com \
  --dns-option ndots:2 \
  my/api:latest

docker exec api cat /etc/resolv.conf
search corp.example.com
nameserver 10.10.0.53
nameserver 10.10.0.54
options ndots:2

Daemon-level config applies to every container that does not override it — useful for a host-wide split-horizon resolver:

{
  "dns": ["10.10.0.53", "10.10.0.54"],
  "dns-search": ["corp.example.com"]
}

And in Compose it is per service, which is usually the right granularity:

services:
  api:
    image: my/api:latest
    dns:
      - 10.10.0.53
    dns_search:
      - corp.example.com
    dns_opt:
      - timeout:2
      - attempts:2

Restart the daemon after editing daemon.json; the container-level and Compose settings take effect at container creation.

The embedded DNS server still fronts everything

Here is the part that confuses people: on a user-defined network, --dns does not replace the resolver in resolv.conf. Docker points the container at its embedded DNS server at 127.0.0.11, that server answers for container names and aliases on the same network, and it forwards everything else to the servers you configured — your --dns values become the upstream list. That split is why ping db and ping registry.internal can behave completely differently in the same container.

Two consequences worth knowing:

  • Do not put 127.0.0.11 in --dns yourself. It is the address Docker already installs in front; your flag is for upstream servers. Conversely, if an application insists on being handed an explicit DNS server address, the docs say to give it 127.0.0.11 — that is the embedded server, and it will do the right thing.
  • Query semantics differ by network type. On a user-defined network, the embedded server queries upstream servers in order and stops at the first successful response or an NXDOMAIN. On the default bridge, containers get a copy of the host’s resolv.conf and their own resolver library decides — some query in parallel and take the first reply, even if it is NXDOMAIN. Two containers with identical flag values can therefore disagree about the same name when one is on the default bridge.

Containers sharing another container’s network stack (--network container:name) cannot take --dns, --dns-search, or --dns-option at all — they inherit the network namespace they joined.

Search domains and short names

--dns-search is what makes api.corp.example.com work when you type api. Each entry is appended to the search line, and the resolver tries them in order before giving up and treating the name as fully qualified. Combined with ndots (via --dns-option), it is also the mechanism behind surprising resolutions: a name with fewer dots than ndots gets expanded against every search domain first, so a name you swore pointed at a container can come back with a corporate answer instead. When resolution is wrong rather than failing, read the search path first.

For container-to-container names, none of this is doing the work — that is the embedded DNS resolving network-local names, as covered in the embedded DNS post.

Verify it properly

# What did the container actually get?
docker exec api cat /etc/resolv.conf

# Does resolution work, and which server answered?
docker exec api nslookup registry.internal
docker exec api dig +short registry.internal

# Short-name expansion: which suffix won?
docker exec api getent hosts api

nslookup/dig test the resolver path in isolation, so a failure here with a working connection test later tells you the problem is DNS, not routing. Alpine images ship nslookup from busybox; for dig, use apk add bind-tools or apt-get install dnsutils.

When you actually need this

  • Split-horizon corporate DNS. The host uses 10.10.0.53; containers that must see the internal view need it explicitly, especially when the host picks up resolvers from DHCP or VPN that containers should not use.
  • Local test zones. A dnsmasq or CoreDNS container serving .test records: point the app containers at the bridge gateway (or that container’s IP) with --dns, and add --dns-search test.
  • Blocking or filtered resolvers in CI. Pin job containers to your internal resolver so builds do not depend on whatever DNS the runner happened to get.
  • Offline/air-gapped hosts. Without a reachable upstream, forwarded queries time out and applications see slow failures rather than clean NXDOMAINs.

Traps, especially on Docker Desktop

The classic Linux mistake is pointing --dns at a host-local resolver: --dns 127.0.0.1 refers to the container’s own loopback address — the docs call this out explicitly — so you get nothing. On a bridge network, use the host’s bridge address instead (for the default bridge, 172.17.0.1; for a user-defined bridge, that network’s gateway from docker network inspect).

Docker Desktop differs in ways that matter. The engine runs inside a VM and container traffic is funnelled through the Desktop backend process, there is no docker0 on your host, and Desktop exposes a DNS resolution behaviour setting under Settings → Network that filters returned A or AAAA records to match the host’s supported IP families — if AAAA filtering is off on an IPv4-only network, you can see hangs that look like resolver failures. Reach host-side services with host.docker.internal rather than a loopback address, and if names resolve on Linux but not on a laptop, compare resolv.conf in both before suspecting the application.

The bottom line

Container DNS is three layers of the same three knobs: servers, search domains, and options, settable per container, per daemon, or per Compose service — with --dns-option / dns_opt naming quirks that are worth getting right the first time. On user-defined networks the embedded server at 127.0.0.11 stays in front and forwards to whatever you configured, so your flags tune upstream resolution rather than replacing it. Read resolv.conf, test with nslookup or dig, and check the search path before you blame the application.

Further reading