Pi-hole Running Docker Desktop on MacOSX: Network Mode: host Not Filtering

Understanding the Network Isolation

When you use network_mode: host in a Docker Compose configuration, the container shares the network stack of the daemon running it. On native Linux systems, this means sharing the host's network interface directly. However, Docker Desktop for macOS operates differently. It does not run directly on the kernel; instead, it runs a lightweight Linux virtual machine (VM) using HyperKit or Apple Virtualization Framework.

In this architecture, the "host" network is actually the network namespace of that internal Linux VM. When Pi-hole binds to 0.0.0.0 or localhost within that VM, it is listening on the VM's internal loopback or virtual interfaces. Your macOS host cannot reach these services via 127.0.0.1 unless specific port forwarding rules are explicitly configured in Docker Desktop settings, which often fails for DNS traffic due to how macOS handles system-level DNS resolution.

The Recommended Solution: Bridge Networking

The most robust way to solve this is to remove network_mode: host and rely on the default bridge network. This allows Docker to manage IP assignment and port mapping automatically. You need to modify your docker-compose.yml file to expose the DNS port (53) to the host.

First, locate your docker-compose.yml file for the Pi-hole service. Remove any lines containing network_mode: host. Then, ensure the ports are mapped correctly. The standard configuration requires mapping UDP port 53 to the host, as DNS primarily uses UDP.

version: '3'
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: always
    ports:
      - "53:53/udp"
      - "53:53/tcp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'your_secure_password'
    volumes:
      - './etc-pihole/:/etc/pihole/'
      - './etc-dnsmasq.d/:/etc/dnsmasq.d/'

After saving the file, restart the container using docker-compose down && docker-compose up -d. Docker will assign an internal IP address to the container, typically something like 172.18.0.2. You can verify this by running docker inspect pihole --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'.

Configuring macOS DNS Resolution

Once the container is running on the bridge network, you must tell macOS to send DNS queries to the Pi-hole container's IP address. Go to System Preferences > Network. Select your active connection (Wi-Fi or Ethernet) and click Advanced. Navigate to the DNS tab.

Add the IP address of your Pi-hole container to the list of DNS servers. Move it to the top of the list to ensure it takes precedence. Click OK and apply the changes. You may need to renew the DHCP lease or toggle Wi-Fi off and on to clear the cache.

If you prefer not to change system-wide DNS settings, you can create a local resolver configuration. Create a file at /etc/resolver/local with the following content:

domain local
nameserver 172.18.0.2

This approach directs all queries for the .local domain to your Pi-hole instance without affecting other internet traffic. Replace 172.18.0.2 with the actual IP assigned to your container. Note that if you restart the container frequently, the IP might change unless you define a custom network with static IPs.

Static IP Configuration for Stability

To prevent IP changes after container restarts, define a custom bridge network in your docker-compose.yml. This ensures Pi-hole always gets the same IP address, making your DNS configuration stable.

version: '3'
networks:
  pihole-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/24

services:
  pihole:
    image: pihole/pihole:latest
    networks:
      pihole-net:
        ipv4_address: 172.20.0.5
    ports:
      - "53:53/udp"
      - "53:53/tcp"
      - "80:80/tcp"
      - "443:443/tcp"

With this setup, your macOS DNS server should always point to 172.20.0.5. This method is particularly useful if you have multiple containers or complex networking requirements. It also aligns with best practices for container orchestration, ensuring predictable behavior across reboots.

Verifying Functionality
After applying these changes, verify that Pi-hole is filtering correctly. Open Terminal on macOS and run dig @172.20.0.5 example.com. If you receive a response from the Pi-hole IP and see the query being logged in the Pi-hole web interface, the setup is successful. You can also check the admin dashboard to view blocked ads and queried domains.
If you encounter issues, ensure that no other local DNS services, such as mDNSResponder, are interfering. You can flush the DNS cache on macOS by running dscacheutil -flushcache; sudo killall -HUP mDNSResponder. This forces the system to re-query the new DNS server immediately.

Frequently Asked Questions

Why did my Pi-hole stop working after a Docker update?
Docker updates sometimes reset network configurations or change default bridge subnets. Always check your container's IP address after an update using docker inspect and update your macOS DNS settings accordingly. Using static IPs in a custom network prevents this drift entirely.

Can I use host network mode with port forwarding?
While technically possible, configuring explicit port forwarding for DNS over UDP in Docker Desktop on macOS is notoriously difficult and often unreliable. Switching to bridge networking is significantly more stable and easier to maintain long-term.

How do I handle IPv6 with Pi-hole on Docker?
Pi-hole supports IPv6, but macOS DNS handling for IPv6 can be complex. Ensure your router advertises IPv6 prefixes correctly and that your Pi-hole container has an IPv6 address assigned. You may need to add the IPv6 address to your macOS DNS servers manually if automatic discovery fails.

What if I want to use Pi-hole only for specific apps?
You can achieve this by using split DNS configurations as described earlier with the /etc/resolver/ directory. This allows you to route only certain domains through Pi-hole while leaving general internet traffic unaffected, providing granular control over your network security.

Is there a risk of DNS loops when using bridge networks?
Yes, if your macOS host tries to resolve the Pi-hole container's IP via itself, it can create a loop. Always ensure your macOS DNS server points directly to the container's IP, not to localhost or the gateway IP, to avoid circular dependencies.