Inspecting Docker Network Configuration with `docker network inspect`
A field-by-field guide to reading docker network inspect output: IPAM subnets and gateways, per-container IPs and MACs, options, labels, and overlay peers.
Published on • November 19, 2026
AI Assistant

A container can’t reach the database, and both “are on the same network” according to whoever wrote the Compose file. Before you start tcpdump, run docker network inspect. It is Docker’s ground truth for a network: which subnet was carved out, where the gateway sits, who is attached right now, and which driver options were baked in at creation time. The command itself is trivial — docker network inspect [OPTIONS] NETWORK [NETWORK...], with only --format and --verbose as flags — so this post is about the part people actually struggle with: reading the output.
The top-level fields
Rendering one network as JSON gives you a fixed set of fields. The ones worth knowing before you go scrolling:
| Field | What it tells you |
|---|---|
Name, Id | Human name and the 64-char network ID (the short ID in docker network ls is a prefix of it) |
Created | When the network was created, in RFC 3339 with nanoseconds |
Scope | local for normal networks, swarm for cluster-wide overlay networks |
Driver | bridge, overlay, macvlan, ipvlan, host, none |
EnableIPv4 / EnableIPv6 | Address families configured at creation (--ipv4=false, --ipv6) |
Internal | true if you passed --internal: no default route, firewall rules drop external traffic |
Attachable / Ingress | Swarm concepts: whether plain containers can join, and whether it is the routing-mesh network |
IPAM | Subnet(s), gateway(s), optional IP range and auxiliary addresses |
Options | Driver options you set with -o |
Labels | Metadata you set with --label |
Containers | Every attached endpoint: name, MAC, IPv4, IPv6 |
Peers / Services | Overlay/swarm extras, only visible in verbose mode |
Internal: true is a quick answer to “is this network supposed to be able to reach the internet?” — an internal bridge configures no default route and drops traffic to and from other networks, while still allowing container-to-container traffic and communication with the gateway address.
IPAM: subnet, gateway, and where addresses come from
The IPAM block is where addressing lives. A user-defined network created with --subnet and --ip-range shows all three parts:
$ docker network inspect app-net --format '{{json .IPAM}}' | jq .
{
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.5.0/24",
"Gateway": "172.20.0.1"
}
],
"Options": {}
}
Two details that trip people up. First, the gateway is not a container — it is the bridge address held by the Docker host, and it is who containers send to when the destination is off-network. Second, IPRange only appears when you constrained allocation with --ip-range; without it, Docker allocates from the whole subnet. If IPAM.Config is empty, the network has no IPv4 configuration at all — which is exactly what docker network create --ipv4=false produces.
When no --subnet was given, Docker pulled a block from the daemon’s default-address-pools, which is why your networks show up as 172.18.x, 172.19.x, and so on in creation order.
The Containers block: who has which IP
Each attached endpoint renders with a name, endpoint ID, MAC address, and addresses in CIDR form:
$ docker network inspect app-net --format '{{range .Containers}}{{.Name}} {{.IPv4Address}} {{.MacAddress}}{{"\n"}}{{end}}'
api 172.20.0.3/16 02:42:ac14:00:03
db 172.20.0.4/16 02:42:ac14:00:04
Note the /16 suffix: those are prefixes, not bare addresses. In the raw JSON the Containers object is keyed by full container ID, but the Name field inside each entry is what you recognise. This block is the fastest way to answer “who is using that IP?” when something conflicts, and it is the authoritative membership list — two containers on different networks will never appear together here, no matter what the Compose file claims.
Options and labels
Options echoes back the -o driver options passed at creation time, which makes it the place to check whether a network really is configured the way you think:
$ docker network inspect isolated-net --format '{{json .Options}}' | jq .
{
"com.docker.network.bridge.enable_icc": "false",
"com.docker.network.bridge.host_binding_ipv4": "127.0.0.1",
"com.docker.network.driver.mtu": "1400"
}
com.docker.network.driver.mtu and com.docker.network.bridge.host_binding_ipv4 are the two that matter most in practice — one decides your packet size behaviour, the other decides what address plain -p 8080:80 binds to.
Labels is metadata you attached with docker network create --label com.example.team=payments. Labels are how you keep track of networks you did not create yourself:
docker network ls --filter label=com.example.team=payments
docker network inspect app-net --format '{{json .Labels}}'
Peers, services, and verbose mode
--verbose is documented as “verbose output for diagnostics”, and it is what unlocks two extra sections:
Peers— only present for overlay networks: the swarm nodes participating in the network, with their names and addresses. Empty output here on an overlay usually means the network has not propagated to that node yet.Services— only present for swarm-scope networks: tasks attached to the network and their endpoint IPs.
Local bridge networks have neither, so do not go hunting for them there.
Recipes: --format and jq
Go templates handle the common one-liners; jq handles anything with structure. A few you will reuse:
# The gateway of a network
docker network inspect app-net --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'
# Two fields side by side
docker network inspect app-net --format '{{printf "%s\t%s\t%s" .Name .Driver .Scope}}'
# Every container on every network, as TSV
docker network ls -q | xargs docker network inspect |
jq -r '.[] | .Name as $net | .Containers[]? | "\($net)\t\(.Name)\t\(.IPv4Address)"'
The {{json .Something}} | jq pattern is the escape hatch: any field you can point a template at can be piped into jq for filtering, so you never have to remember jq’s whole path syntax for Docker’s nested shapes.
A debugging workflow
When connectivity breaks, run the checks in this order:
- Membership and addresses —
docker network inspect <net>. Are both containers inContainers? Do their IPs sit in the printedIPAM.Configsubnet? - Is it internal? — check
Internaland theOptions. An internal network has no route off itself by design. - Driver options — MTU, ICC, default bind address. Mismatched MTU between a network and its underlay produces hangs that look like application bugs.
- Labels — confirm you are inspecting the network you think you are; project-scoped Compose networks have surprising names like
myproject_back. - Container side —
docker inspect <container>and read.NetworkSettings.Networks. That view is per-container: for each network it lists the endpoint’sGateway,IPAddress,IPPrefixLen,MacAddress, and the network-scoped aliases. Network inspect tells you what the network sees; container inspect tells you what the container sees — including when a container is attached to several networks at once.
The two views together resolve almost every “it works by IP but not by name” report: if the container is on a different network than its peer, the names will not resolve, and the fix is docker network connect, not DNS surgery.
The bottom line
docker network inspect is a small command with a dense payload: addressing in IPAM, live membership in Containers, creation-time intent in Options and Labels, and swarm topology in verbose Peers. Learn to pull the four fields you need with --format instead of reading the whole blob, and network troubleshooting becomes a thirty-second check rather than an investigation.