Skip to content
Blog

Custom Subnets, IPAM, and Static Container IPs in Docker

Pin Docker subnets with --subnet, --gateway, and --ip-range, assign fixed container addresses with --ip, and control auto-allocation through default-address-pools.

Published on • November 19, 2026

AI Assistant

Docker’s allocator hands out subnets on its own — until one of them lands on your corporate VPN range and routing breaks in a way that looks like a DNS problem. Pinning your CIDRs takes twenty seconds per network, and it’s the difference between a firewall rule you can write and an address plan you can only discover. Here’s the full toolkit: explicit subnets, static container IPs, and the pools Docker allocates from when you stay quiet.

Address a network explicitly

Every flag you need is on docker network create:

docker network create \
  --subnet 10.50.0.0/24 \
  --gateway 10.50.0.1 \
  --ip-range 10.50.0.128/25 \
  demo-ipam

Inspect what IPAM recorded:

docker network inspect demo-ipam --format '{{json .IPAM.Config}}'
[{"Subnet":"10.50.0.0/24","IPRange":"10.50.0.128/25","Gateway":"10.50.0.1"}]

The three pieces do different jobs:

FlagPurpose
--subnetThe CIDR the network owns; dynamic allocation happens inside it
--gatewayGateway address for the master subnet (Docker picks one if omitted)
--ip-rangeDynamic IPs come from this sub-range only — everything else stays reserved
--aux-addressNamed addresses to exclude, e.g. --aux-address="my-router=192.168.32.129"

Two constraints from the create reference worth knowing before you plan around them: a bridge network takes exactly one subnet — a second --subnet fails with bridge driver doesn't support multiple subnets — while overlay, macvlan, and ipvlan networks accept several (the docs show two /25s for overlay to respect the 256-IP guidance). It’s same-family duplication the bridge refuses, though: the docs’ own explicit-subnet example pairs an IPv4 and an IPv6 block, and that works fine:

docker network create --ipv6 --subnet 192.0.2.0/24 --subnet 2001:db8::/64 mynet

One more default worth overriding deliberately: if you omit --gateway, Docker Engine “selects one for you from inside a preferred pool.” Fine until your network team asks where this subnet’s traffic actually egresses — then it isn’t fine. And --ip-range isn’t just reservation: it’s the mechanism that makes static IPs safe, as we’ll see below.

Static container IPs with —ip

Assign a fixed address at run time — but only on a user-defined network:

docker run -dit --name ipam1 --network demo-ipam --ip 10.50.0.69 alpine ash
docker exec ipam1 ip -4 addr show eth0
    inet 10.50.0.69/24 brd 10.50.0.255 scope global eth0

Try it on the default bridge and the daemon refuses, with an error that states the rule outright:

docker run -dit --name defbridge --ip 172.17.0.99 alpine ash
docker: Error response from daemon: invalid config for network bridge: invalid endpoint settings:
user-specified IP address is supported on user-defined networks only

The docker run reference adds the second requirement: “to assign a static IP to containers, you must specify subnet block for the network” — an auto-allocated network can’t guarantee your address exists. The same --ip/--ip6 flags work later via docker network connect --ip, and per-interface addresses are the reason the connect reference recommends this pattern: create the network with an --ip-range, keep your static addresses outside it, and dynamic allocation can never steal them from a restarting container:

docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network
docker network connect --ip 172.20.128.2 multi-host-network container2

If the address is taken when the container restarts, it fails to start — the docs are explicit about that — so this reservation trick is what makes --ip production-safe.

The IPAM driver: default, and plugins

--ipam-driver sets the address-management driver; the built-in one is default, which is what you get without the flag:

docker network create --ipam-driver=default demo-ipamdef   # works
docker network create --ipam-driver=debug demo-badipam
Error response from daemon: plugin "debug" not found

There is no debug (or host, or alternate) IPAM driver hiding in the daemon — anything other than default must be an installed plugin, typically a third-party IPAM integration that manages addresses in an external system. Alongside it sits --ipam-opt for driver-specific options. For the overwhelming majority of hosts, the default IPAM driver plus explicit --subnet flags is the whole story.

Controlling auto-allocation: default-address-pools

When you don’t pass --subnet, Docker carves networks from predefined pools. The networking overview publishes the built-in defaults:

{
  "default-address-pools": [
    { "base": "172.17.0.0/16", "size": 16 },
    { "base": "172.18.0.0/16", "size": 16 },
    { "base": "172.19.0.0/16", "size": 16 },
    { "base": "172.20.0.0/14", "size": 16 },
    { "base": "172.24.0.0/14", "size": 16 },
    { "base": "172.28.0.0/14", "size": 16 },
    { "base": "192.168.0.0/16", "size": 20 }
  ]
}

base is the range to allocate from; size is the prefix length handed to each network. Those big defaults limit how many networks you can create — the docs show that one base divided finely yields more:

{ "default-address-pools": [{ "base": "172.17.0.0/16", "size": 24 }] }

That configuration supports 256 networks (172.17.0.0/24 through 172.17.255.0/24). This lives in daemon.json next to bip, and the mechanics of editing and reloading it are covered in Configuring the Docker daemon with daemon.json. Docker does try to avoid prefixes already in use on the host, but the docs advise customizing pools “to prevent routing conflicts in some network environments” — corporate ranges being the usual suspect. IPv6 has one more allocator behavior worth knowing: with no v6 blocks in default-address-pools, Docker carves IPv6 subnets from a Unique Local Address (ULA) prefix — perfectly fine for isolation, useless if your upstream expects globally routable v6. Put your own pools in daemon.json if that matters.

One version caveat from the docs: you can request a prefix length directly with unspecified addresses — docker network create --subnet 0.0.0.0/24 mynet allocates a /24 from the pools — but that support arrived in Docker 29.0.0, and networks created that way become unusable if you downgrade.

Why pinning CIDRs matters

Three reasons, in order of how much pain they prevent:

  1. Firewall rules. iptables -s 10.50.0.0/24 is a rule; iptables -s against whatever the allocator picked this morning is a liability.
  2. Avoiding collisions. VPNs, on-prem ranges, and cloud VPCs overlap with Docker’s defaults more often than not. A collision surfaces as intermittent, inexplicable connectivity — the worst kind.
  3. Service discovery and integrations. External systems (monitoring, allowlists, site-to-site routes) need stable addressing; containers get fresh IPs constantly, but the network’s CIDR should never move.

Audit what’s allocated at any time with the same inspect command — .IPAM.Config for subnets, and the Containers section for per-endpoint addresses:

docker network inspect demo-ipam --format '{{range .IPAM.Config}}subnet={{.Subnet}} range={{.IPRange}} gw={{.Gateway}}{{"\n"}}{{end}}'
subnet=10.50.0.0/24 range=10.50.0.128/25 gw=10.50.0.1

docker network inspect takes multiple networks, so an address-plan audit is one command:

docker network inspect verify-a verify-b --format '{{.Name}} -> {{range .IPAM.Config}}{{.Subnet}} {{end}}'
verify-a -> 10.80.0.0/24
verify-b -> 10.81.0.0/24

Keep that output next to your firewall’s source lists; when they disagree, one of them is wrong, and it isn’t the routing table.

The bottom line

Docker’s IPAM gives you two levers: pin each network’s CIDR at creation with --subnet/--gateway/--ip-range, and pin addresses that must not move with --ip — always on a user-defined network, ideally outside the dynamic --ip-range. When you let Docker allocate instead, take ten minutes once to set default-address-pools in daemon.json so every auto-created network lands in space you actually own. Address plans you choose beat address plans you discover.

Further reading