Docker Network MTU Tuning: Defaults, Diagnosis, and Production Configuration

Published November 8, 2022

No hand-waving. Every MTU setting: what it does, the default if you omit it, what breaks when it's wrong, and exactly how to calculate the right value — with real numbers.

MTU problems are maddening because everything looks fine. Ping works. SSH connects. DNS resolves. Then HTTPS hangs on large pages, Docker pulls stall halfway through, and your monitoring shows nothing because small packets still get through.

This guide walks through Docker networking MTU from first principles to production. For every important setting you'll get four things:

1. What it does — in plain language
2. Default value — what Docker uses if you write nothing
3. What goes wrong — if you leave the default or set it wrong
4. How to calculate — step-by-step with real numbers

We'll use a concrete reference server throughout:

Adjust the numbers for your environment. The method stays the same.

1. What MTU is and why Docker makes it worse

MTU (Maximum Transmission Unit) is the largest IP packet size a network interface can send without fragmentation. Standard Ethernet is 1500 bytes. Every hop along the path must support at least that size — or packets get fragmented or silently dropped.

Docker adds encapsulation overhead. A container on a bridge network doesn't talk directly on the host NIC. Traffic goes through a virtual bridge (docker0 or a custom bridge), often through iptables/NAT, and sometimes through an overlay tunnel (VXLAN adds 50 bytes). Each layer eats into your effective MTU budget.

Reference scenarios — know your path MTU before tuning Docker:

Standard Ethernet (office LAN, bare metal): 1500 MTU end-to-end. Docker bridge default 1500 usually works.

Cloud VPC (AWS, GCP, Azure, Hetzner): 1500 MTU on the host NIC. Same as Ethernet — but check if you're behind a VPN or transit gateway that lowers it.

WireGuard VPN (typical config): Interface MTU 1420. Path MTU to remote peers is ≤ 1420. Docker bridge at 1500 causes black-hole behavior for large packets.

2. Common symptoms — when MTU is your problem

These patterns scream MTU mismatch long before you find the root cause:

• SSH works, HTTPS hangs — SSH sends small packets; TLS handshakes and page loads send larger ones. Classic MTU black hole.
• Slow TLS / SSL connections — Certificate chains and ClientHello messages exceed the broken path. Connection eventually succeeds after TCP retries shrink the window — feels like "slow SSL."
• Intermittent timeouts — Small API calls succeed; file uploads, docker pull, or database dumps fail or stall randomly.
• Ping works without payload, fails with size — ping 8.8.8.8 succeeds (64 bytes). ping -s 1472 8.8.8.8 fails.
• Works on host network, broken in container — Host uses correct path MTU; container bridge still at 1500.
• Works locally, broken across VPN/site-to-site — Remote site has lower MTU; local Docker defaults assume 1500.

3. Diagnosis commands — find the real MTU

Don't guess. Run these before changing anything.

3.1 Check host interface MTU

# All interfaces and their MTU
ip link show

# Specific interface (e.g. WireGuard)
ip link show wg0 | grep mtu

# Example output:
# 3: wg0: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1420 qdisc noqueue

3.2 Path MTU discovery with ping (don't fragment)

On the host, Linux ping supports the DF (Don't Fragment) bit:

# Linux host: ping with DF bit set (won't fragment)
ping -M do -s 1472 8.8.8.8        # 1472 + 28 headers = 1500 total
ping -M do -s 1372 8.8.8.8        # 1372 + 28 = 1400

# Increase -s until you get "Frag needed" or 100% loss
# Last working size + 28 = your path MTU

From inside a container: Alpine's default busybox ping does not support -M do on all versions. Install iputils or use tracepath instead:

# Recommended: tracepath (works on Alpine without extra flags)
docker run --rm alpine sh -c "apk add -q iputils && tracepath -n 8.8.8.8 | head -3"

# Alternative: iputils ping with DF bit
docker run --rm alpine sh -c "apk add -q iputils && ping -M do -s 1372 -c 3 8.8.8.8"

Don't trust container ping alone. Always compare host tracepath vs container tracepath to the same destination. If they differ, Docker network MTU is wrong.

3.3 tracepath — automatic PMTU discovery

# Shows hop-by-hop and estimated path MTU
tracepath 8.8.8.8

# From container (install iputils if needed)
docker run --rm alpine sh -c "apk add iputils && tracepath 8.8.8.8"

# Example output:
#  1:  172.18.0.1                                         0.1ms pmtu 1500
#  1:  172.18.0.1                                         0.2ms pmtu 1420  ← VPN lowered it

3.4 Inspect Docker network MTU

# List networks
docker network ls

# Check MTU on a specific network
docker network inspect bridge --format '{{json .Options}}'
docker network inspect myapp_web --format '{{range $k,$v := .Options}}{{$k}}={{$v}} {{end}}'

# Full inspect (look for "com.docker.network.driver.mtu" in Options)
docker network inspect myapp_web | grep -i mtu

# Check docker0 bridge MTU on host
ip link show docker0 | grep mtu

3.5 Compare host vs container

# Host path MTU
tracepath -n 1.1.1.1 | head -1

# Container path MTU (same destination)
docker run --rm --network myapp_web alpine sh -c \
  "apk add -q iputils && tracepath -n 1.1.1.1 | head -1"

# If host shows pmtu 1420 but container shows 1500 → fix Docker network MTU

4. Docker bridge network MTU (driver_opts)

Bridge networks are the default for docker compose stacks. Each user-defined bridge can have its own MTU via driver_opts.

4.1 Complete docker-compose.yml — WireGuard host example

services:
  nginx:
    image: nginx:1.27-alpine
    container_name: nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    networks:
      - web
      - backend
    depends_on:
      - api

  api:
    image: myapp/api:latest
    container_name: api
    restart: unless-stopped
    networks:
      - backend
      - db

  postgres:
    image: postgres:16-alpine
    container_name: postgres
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - db

networks:
  web:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1420"

  backend:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1420"

  db:
    driver: bridge
    internal: true
    driver_opts:
      com.docker.network.driver.mtu: "1420"

volumes:
  pgdata:

4.2 docker-compose.yml — standard cloud (1500, explicit for documentation)

networks:
  web:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1500"

  backend:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1500"

4.3 docker-compose.yml — Swarm overlay

networks:
  web:
    driver: overlay
    driver_opts:
      com.docker.network.driver.mtu: "1370"
    attachable: true

  backend:
    driver: overlay
    driver_opts:
      com.docker.network.driver.mtu: "1370"
    internal: true

Important: Changing MTU in compose only applies when the network is created. Existing networks keep their old MTU. You must recreate:

docker compose down
docker network rm myapp_web myapp_backend   # if not removed by down
docker compose up -d

5. Global default MTU — /etc/docker/daemon.json

# /etc/docker/daemon.json
{
  "mtu": 1420,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

# Apply changes
sudo systemctl restart docker

# Verify docker0 MTU after restart
ip link show docker0 | grep mtu
# Expected: mtu 1420

# Verify default bridge network
docker network inspect bridge --format '{{index .Options "com.docker.network.driver.mtu"}}'
# Expected: 1420

Caution: Restarting Docker stops all running containers unless you use live-restore. Plan a maintenance window.

6. TCP MSS — the formula that actually fixes TLS slowness

Linux usually clamps MSS automatically via route MTU (tcp_mtu_probing). But when Docker bridge MTU is wrong, the kernel's MSS clamping is also wrong. Fix the interface MTU first — MSS follows.

# Enable TCP MTU probing as safety net (host)
sudo sysctl -w net.ipv4.tcp_mtu_probing=1

# Persist in /etc/sysctl.d/99-docker-mtu.conf
net.ipv4.tcp_mtu_probing = 1

7. Overlay / Swarm MTU considerations

Swarm overlay networks encapsulate container traffic in VXLAN (UDP port 4789). VXLAN adds 50 bytes of overhead per packet.

Swarm checklist: Set the same overlay MTU on every node in the cluster. Mixed MTU across nodes causes asymmetric routing failures that are hard to debug. After changing, recreate overlay networks: docker network rm then redeploy stack.

# Create overlay manually with correct MTU
docker network create \
  --driver overlay \
  --opt com.docker.network.driver.mtu=1370 \
  --attachable \
  myoverlay

8. macvlan and host network modes

networks:
  macvlan_net:
    driver: macvlan
    driver_opts:
      parent: eth0
      com.docker.network.driver.mtu: "1420"
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

9. Worked examples — full calculations

Example A: WireGuard VPN host, bridge compose stack

Example B: Cloud VPS (1500), no VPN

Example C: Swarm cluster over WireGuard

Example D: PPPoE home connection (1492)

10. Master defaults table — quick lookup

Setting                              │ Default (if omitted) │ WireGuard example │ Cloud example
─────────────────────────────────────┼──────────────────────┼───────────────────┼────────────────
daemon.json mtu                      │ 1500                 │ 1420              │ 1500 (omit)
bridge driver_opts mtu               │ 1500                 │ 1420              │ 1500 (omit)
overlay driver_opts mtu              │ 1500 (wrong for VXLAN)│ 1370              │ 1450 (1500−50)
docker0 bridge MTU                   │ 1500                 │ 1420              │ 1500
container eth0 MTU (bridge)          │ inherits network     │ 1420              │ 1500
IPv4 TCP MSS                         │ MTU − 40             │ 1380              │ 1460
VXLAN overhead (overlay)             │ not accounted for    │ subtract 50       │ subtract 50
host network_mode                    │ uses host NIC MTU    │ 1420              │ 1500

11. Troubleshooting — symptom → cause → fix

Symptom                              │ Likely cause                         │ Fix
─────────────────────────────────────┼──────────────────────────────────────┼──────────────────────────────
SSH works, HTTPS hangs               │ MTU black hole on large packets      │ Lower Docker network MTU to path MTU
Slow TLS handshake                   │ TCP retries on oversized segments    │ Fix bridge MTU; enable tcp_mtu_probing
Small API calls OK, uploads fail     │ Payload exceeds path MTU             │ tracepath from container; set driver_opts
ping works, ping -s 1472 fails       │ Path MTU < 1500                      │ Match Docker MTU to tracepath result
Works on host, broken in container   │ Bridge MTU 1500, host path lower     │ driver_opts mtu + recreate network
Swarm service unreachable cross-node │ Overlay MTU ignores VXLAN overhead   │ overlay MTU = path MTU − 50
Fixed MTU but still broken           │ Old network not recreated            │ docker compose down; docker network rm; up
docker pull stalls mid-download      │ Registry traffic hits MTU limit      │ Fix daemon.json mtu; restart docker
Intermittent DB replication lag      │ Large WAL packets dropped            │ Set db network MTU; verify with tracepath
Changes to daemon.json no effect     │ Didn't restart Docker                │ systemctl restart docker; verify docker0

12. Practical walkthrough — fix MTU on a live host

Use this sequence when symptoms match Section 2. Do not change MTU blindly.

Step 1 — Confirm path MTU on the host (before Docker)

tracepath -n 8.8.8.8 | head -3
ip link show | grep -E '^[0-9]+:|mtu'

Write down the lowest pmtu reported. Example: WireGuard → 1420. Plain cloud VPS → 1500.

Step 2 — Check what Docker networks actually use

docker network ls
docker network inspect myapp_web --format '{{index .Options "com.docker.network.driver.mtu"}}'
docker run --rm --network myapp_web alpine ip link show eth0 | grep mtu

If container eth0 shows 1500 but host path is 1420 → you found the bug.

Step 3 — Set daemon.json (docker0 + safety net)

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "mtu": 1420
}
EOF
sudo systemctl restart docker
ip link show docker0 | grep mtu

Step 4 — Set Compose driver_opts (the real fix for stacks)

Add to every network in your compose file:

networks:
  web:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1420"

Step 5 — Recreate networks (required)

docker compose down
docker network rm myapp_web myapp_backend 2>/dev/null || true
docker compose up -d

MTU is applied at network creation. Editing compose without recreating the network does nothing.

Step 6 — Verify from inside the app container

docker exec api ip link show eth0 | grep mtu
docker exec api sh -c "apk add -q iputils && tracepath -n 1.1.1.1 | head -2"

# Payload test: (path_mtu - 28) for ping headers
# 1420 path → ping -s 1392
docker exec api sh -c "apk add -q iputils && ping -M do -s 1392 -c 3 8.8.8.8"

Step 7 — Test real workloads, not just ping

curl -v https://example.com          # TLS handshake uses larger packets
docker pull nginx:alpine             # registry download
# Your actual slow endpoint / file upload

13. Production checklist

1. Measure path MTU on the host — tracepath 8.8.8.8 or ping -M do -s sweep before touching Docker config.
2. Document your scenario — Standard Ethernet (1500), cloud (1500), WireGuard (1420), PPPoE (1492). Write it down in your runbook.
3. Set daemon.json mtu — Fixes docker0 and ad-hoc containers. Not a substitute for Compose driver_opts.
4. Set driver_opts on every compose network — Explicit MTU per network. For overlay: path MTU − 50 (cloud 1500 → overlay 1450).
5. Recreate networks after changes — MTU is set at network creation time, not live-updated.
6. Verify from inside a container — ip link show eth0, tracepath, ping -M do -s with calculated payload size.
7. Enable tcp_mtu_probing — Safety net on hosts with variable paths (mobile VPN, multi-WAN).
8. Same MTU on all Swarm nodes — Mixed configs cause asymmetric failures.
9. Test large transfers — docker pull, HTTPS page load, file upload — not just ping.
10. Monitor after VPN changes — Adding WireGuard or changing tunnel config changes path MTU. Recalculate.

14. Wrapping up

MTU issues hide behind "the network seems fine." The defaults assume 1500-byte Ethernet everywhere — which breaks the moment you add a VPN, PPPoE, or VXLAN overlay.

The fix is mechanical: find your path MTU on the host, subtract overlay overhead if any, set that number in driver_opts on every Compose network (and in daemon.json for docker0), recreate networks, verify from inside a container. MSS = MTU − 40 for IPv4 TCP. That's the whole formula.

Start with tracepath on the host. If it shows anything below 1500, your Docker networks need to match — or you'll keep chasing ghosts in application logs.