Step-by-step: Enable and Debug IPv6 in Docker Containers and Bridge Networks on Debian (practical guide)

Docker & Containers · By Kevin Marcondes · Published on Oct 22, 2026 · 8 min read

This step-by-step guide shows how to enable and debug IPv6 for Docker containers and bridge networks on Debian from scratch. You will configure kernel/sysctl, adjust daemon.json, create a bridge with IPv6, and validate connectivity. You'll bring up containers with IPv6 addresses and follow a diagnostic checklist for routes, firewall and address allocation issues.

Prerequisites and how IPv6 works in Docker

You need root access on the Debian host and Docker installed. If Docker is missing, install it following this guide: how to install Docker and Docker Compose.

Docker only assigns IPv6 addresses if the daemon has IPv6 enabled and the network has an IPv6 subnet. By default, the docker0 bridge only has IPv4.

For internal networks use ULA addresses (fd00::/8). For global Internet traffic, prefer a prefix routed to your host by your provider.

Restarting Docker will stop running containers. Plan a maintenance window and use Compose to bring services back up quickly.

This is a practical, focused guide to enable and debug IPv6 in Docker containers and bridge networks on Debian, emphasizing tests and diagnostics.

• Root or sudo access to the Debian server
• Docker and Docker Compose installed
• Optional public IPv6 prefix routed to the host (for IPv6 Internet)
• Backup /etc/docker/daemon.json if it already exists
• A maintenance window to restart the Docker service

1) Check IPv6 support on the Debian host

Before changing Docker, confirm the kernel hasn't disabled IPv6 and that there are IPv6 routes on the host. If the host lacks global IPv6, you can still use ULA internally.

If the disable_ipv6 sysctl returns 1, IPv6 is disabled. We'll enable it in the next step.

# 1. Checar se o IPv6 está habilitado no kernel
sysctl net.ipv6.conf.all.disable_ipv6

# 2. Ver endereços IPv6 do host (global e link-local)
ip -6 addr show

# 3. Rotas IPv6
ip -6 route

# 4. Teste de conectividade externa IPv6 (opcional)
ping -6 -c 2 2606:4700:4700::1111 || true

2) Enable IPv6 and forwarding in the kernel (sysctl)

Enable IPv6 on the host and enable forwarding between interfaces. This allows Docker bridges to forward IPv6 packets. Applying sysctl affects networking—run it in a safe window.

Set accept_ra=2 to allow routing even when Router Advertisements (RA) are present. On servers this avoids losing the default route when forwarding is active.

cat >/etc/sysctl.d/10-ipv6-docker.conf <<'EOF'
net.ipv6.conf.all.disable_ipv6 = 0
net.ipv6.conf.default.disable_ipv6 = 0
net.ipv6.conf.all.forwarding = 1
net.ipv6.conf.default.forwarding = 1
net.ipv6.conf.all.accept_ra = 2
net.ipv6.conf.default.accept_ra = 2
EOF

# Aplica tudo que está em /etc/sysctl.d
sysctl --system

3) Enable IPv6 in the Docker daemon (daemon.json)

Turn on IPv6 in Docker and set a ULA range for address allocation. Docker will use this range for bridge networks when configured with IPv6.

If daemon.json already exists, merge fields manually so you don't lose settings. Restarting Docker will stop running containers.

mkdir -p /etc/docker
cat >/etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00:dead:beef::/48",
  "ip6tables": true
}
EOF

# Reinicie o Docker (interrompe containers em execução)
systemctl restart docker && systemctl status --no-pager docker

4) Create a Docker bridge with a dedicated IPv6 subnet

Create an explicit bridge network with IPv6. Separate subnets by environment to avoid conflicts. The bridge gateway IPv6 will be the host's address on that network.

After creating the network, inspect it to confirm the IPv6 Subnet and Gateway are present.

# Cria uma rede bridge com IPv4 e IPv6
# Ajuste as faixas conforme sua política de endereçamento
NETWORK_NAME=brv6

docker network create \
  --driver bridge \
  --subnet 172.18.0.0/16 \
  --ipv6 \
  --subnet fd00:dead:beef:1::/64 \
  --gateway fd00:dead:beef:1::1 \
  "$NETWORK_NAME"

# Verifique a configuração
docker network inspect "$NETWORK_NAME" | grep -E 'IPv6|Subnet|Gateway' -n

5) Bring up containers and test IPv6 (Docker Compose)

You can enable IPv6 directly in Compose by defining the network with enable_ipv6 and IPAM. In this example the network is created by Compose and the service receives an IPv6 address automatically.

After bringing the service up, enter the container and verify the IPv6 address and default route.

# docker-compose.yml
version: "3.9"
services:
  app:
    image: alpine:3
    command: ["sh","-lc","ip -6 addr show dev eth0; ip -6 route; sleep 3600"]
    networks:
      - brv6

networks:
  brv6:
    driver: bridge
    enable_ipv6: true
    ipam:
      config:
        - subnet: 172.19.0.0/16
        - subnet: fd00:dead:beef:2::/64
          gateway: fd00:dead:beef:2::1

6) Debugging: routes, firewall rules and Docker logs

If a container doesn't receive IPv6, confirm the network was created with IPv6 and the daemon has ipv6=true. Then check routes and firewall rules.

Debian uses iptables-nft by default. Docker manipulates ip6tables rules when ip6tables=true. Adapt your firewall policy to allow traffic from the bridge.

For host hardening and running Docker with cgroup v2, see: cgroup v2 + systemd for Docker and VPS security checklist.

• Confirm IPv6 on the network: docker network inspect
• Check routes on host and inside the container
• Review ip6tables/nftables for blocking rules
• Check Docker logs for network-related errors

# Inspecione a rede
docker network inspect brv6

# Rotas IPv6 no host
ip -6 route

# Regras IPv6 (iptables-nft)
ip6tables -L -n -v | sed -n '1,120p'

# (Opcional) Ver regras nftables
nft list ruleset | grep -i ip6 || true

# Logs recentes do Docker
journalctl -u docker --since -2h | tail -n +1

7) Verification checklist and practical tests

Use this checklist to confirm everything is working. If an item fails, go back a step and review the configuration.

Monitor the environment continuously. For metrics and dashboards with Compose, see: Prometheus & Grafana with Docker Compose.

This step-by-step guide ensures you validate every layer: kernel, daemon, network and application.

• docker info shows IPv6: true
• docker network inspect lists IPv6 Subnet and Gateway
• Container has an fd00:... address on eth0
• Container can ping -6 the bridge gateway
• Host can ping -6 the container by its ULA address
• IPv6 routes exist on both host and container

8) Common problems and quick fixes

Some errors are common when enabling IPv6 for containers. Below are typical fixes. Do not promise NAT66 without assessing risks; prefer a provider-routed prefix.

To reduce downtime when restarting Docker in production, consider strategies like blue-green with Compose: blue-green deploy.

If you need to revisit the full flow, return to this step-by-step guide and re-validate each step.

• Container only has fe80:: (link-local): recreate the network with --ipv6 and IPv6 IPAM in Compose.
• No IPv6 Internet while using ULA: request a routed /64 from your provider or use a tunnel. NAT66 is possible but nonstandard and complex.
• Forwarding disabled: ensure net.ipv6.conf.all.forwarding=1 and apply sysctl --system.
• Firewall blocking: review IPv6 chains and allow Docker bridge traffic according to your policy.
• daemon.json overwritten: merge keys; restart Docker after validating JSON.
• Changes vanish at reboot: use files in /etc/sysctl.d and avoid only runtime sysctl edits.

Frequently asked questions

Does Docker come with IPv6 enabled by default?

No. You must enable "ipv6": true in daemon.json and use bridge networks created with IPv6. Without that, containers only get IPv4. Then create the network with an fd00::/64 or set enable_ipv6 in Docker Compose.

Do I need a public IPv6 address on my VPS to use IPv6 in containers?

Only if you want IPv6 Internet access. For internal communication between host and containers, ULA (fd00::/8) works. For IPv6 Internet, prefer a public prefix routed to your host and forward it to the bridge.

Can I enable IPv6 only in Docker Compose?

Yes. Define enable_ipv6: true on the Compose network and configure IPAM with an IPv6 subnet. The Docker daemon must also have ipv6=true, otherwise Docker won't allocate v6 addresses.

Should I use iptables or nftables with Docker and IPv6 on Debian?

Debian uses iptables-nft by default. Docker manages ip6tables rules when ip6tables=true. Adjust your firewall policy to allow bridge traffic. Verify with ip6tables -L -n -v and nft list ruleset.

Does restarting Docker cause downtime? How to minimize it?

Yes—restarting Docker stops containers. Schedule a maintenance window and orchestrate recovery with Compose. Blue-green deployment strategies help reduce impact in production; see the blue-green deploy tutorial.

See also

• Tutorial: set up mTLS between Traefik and Docker Compose services using smallstep CA and automatic certificates — step by step
• Tutorial: integrate Sentry into your GitHub Actions deploy pipeline — automatic source map upload & issue creation (PHP & JavaScript)
• Configure retention and compression for Docker container logs with journald + logrotate + rsyslog on a low-disk VPS
• Tutorial: Configure GitHub Actions for integration tests with PostgreSQL in ephemeral containers and automatic migration rollback — a practical guide