Setting Up a Docker Macvlan Network Step by Step
Set up a Docker macvlan network step by step: check the parent interface, verify from a LAN host, add VLAN sub-interfaces and static IPs, and dodge the host-reachability limit.
Published on • November 19, 2026
AI Assistant

macvlan gives every container its own MAC address on your real parent interface, so from the LAN it looks like another physical machine — no NAT, no port mapping, no docker0 in sight. It’s the right tool for appliances that must be visible to the network as themselves, and the wrong tool almost everywhere else. Here’s the complete setup, including the two restrictions that bite in production.
Check the platform before anything else
Docker’s macvlan requirements are unusually strict, and it pays to confirm them before designing anything:
| Requirement | Detail |
|---|---|
| OS | Linux hosts only — not Docker Desktop for Mac or Windows, not Docker Engine on Windows |
| Cloud | Most cloud providers block macvlan; you may need physical access to networking equipment |
| Kernel | Linux 3.9 minimum, 4.0 or later recommended |
| Mode | Not supported in rootless mode |
| Switch gear | Your networking equipment must handle promiscuous mode — one physical interface carrying multiple MAC addresses |
Then confirm the parent interface — the NIC whose subnet your containers will live on:
$ ip -br addr show
lo UNKNOWN 127.0.0.1/8
eth0 UP 192.168.1.250/24
The interface you name as parent must exist and be up; that’s where the traffic physically egresses. Note the host’s subnet (192.168.1.0/24 here) — your macvlan subnet should come from that same LAN, because containers are peers of the host, not behind it.
Create the network
$ docker network create -d macvlan \
--subnet=172.16.86.0/24 \
--gateway=172.16.86.1 \
-o parent=eth0 \
pub_net
3f8a91c2d7b64e05a1c8d92f1b7e4c60a5d9382f16b0e7d4c2a95f1386b0e7d2
-o parent=eth0 is the one driver-specific option that’s mandatory in practice — without a parent there’s no physical network to attach to. If an address in the subnet is already taken by something on your LAN, keep Docker’s allocator away from it:
$ docker network create -d macvlan \
--subnet=192.168.32.0/24 \
--ip-range=192.168.32.128/25 \
--gateway=192.168.32.254 \
--aux-address="my-router=192.168.32.129" \
-o parent=eth0 \
macnet32
--ip-range confines allocation to a slice of the subnet; --aux-address reserves individual addresses so containers never collide with them — handy when a router already owns .129.
Run a container and verify it from the LAN
$ docker run --rm -dit --network pub_net --name web1 alpine:latest sleep 1d
$ docker container inspect web1 --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{.MacAddress}}{{end}}'
172.16.86.2 02:42:ac:10:56:02
$ docker exec web1 ip addr show eth0
9: eth0@tunl0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP
link/ether 02:42:ac:10:56:02 brd ff:ff:ff:ff:ff:ff
inet 172.16.86.2/24 brd 172.16.86.255 scope global eth0
$ docker exec web1 ip route
default via 172.16.86.1 dev eth0
172.16.86.0/24 dev eth0 scope link src 172.16.86.2
Now walk to any other machine on the LAN — the real test:
$ ping -c 2 172.16.86.2
PING 172.16.86.2 (172.16.86.2) 56(84) bytes of data.
64 bytes from 172.16.86.2: icmp_seq=1 ttl=64 time=0.55 ms
64 bytes from 172.16.86.2: icmp_seq=2 ttl=64 time=0.51 ms
$ ip neigh show
172.16.86.2 dev eth0 lladdr 02:42:ac:10:56:02 REACHABLE
To the rest of the network, web1 is simply a host with MAC 02:42:ac:10:56:02 on the segment — ARP resolution, switch MAC tables, and any port-security rules see a normal device, not a NAT’d container.
Pinning addresses
Two knobs control which addresses containers get:
# a specific, predictable IP for one container
$ docker run -d --ip=172.16.86.100 --network pub_net --name db alpine:latest sleep 1d
# or constrain the whole network's allocation, as in the macnet32 example above
--ip on docker run is the one to reach for when something on your LAN (a firewall rule, a allowlist, a peer service) must be able to predict where the container will be.
VLANs: pointing parent at a sub-interface
If your network is segmented, name the parent with a dot. Docker interprets eth0.50 as an 802.1Q sub-interface of eth0 and creates the sub-interface on the fly:
$ docker network create -d macvlan \
--subnet=192.168.50.0/24 \
--gateway=192.168.50.1 \
-o parent=eth0.50 \
macvlan50
$ ip addr show eth0.50 | head -2
3: eth0.50@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP
Containers on macvlan50 live in VLAN 50’s broadcast domain even though the physical NIC is shared — and networks on different VLANs can’t reach each other without a router in between. This is the same trick the ipvlan driver uses, so the topology carries over if you switch drivers later.
The restriction you will hit: host to container
Docker states it plainly: “Containers attached to a macvlan network cannot communicate with the host directly, this is a restriction in the Linux kernel.” Your docker exec works, your LAN ping works, but the host’s own IP can’t be reached from the container. Two documented workarounds:
1. Connect the container to a bridge network as well. Management traffic rides the bridge while the real traffic rides the macvlan:
$ docker network create br-mgmt
$ docker network connect br-mgmt web1
2. Create a macvlan interface on the host itself, on the same parent, with an address inside the Docker network’s subnet:
$ sudo ip link add mac0 link eth0 type macvlan mode bridge
$ sudo ip addr add 172.16.86.10/24 dev mac0
$ sudo ip link set mac0 up
$ ping -c 2 172.16.86.2
PING 172.16.86.2 (172.16.86.2) 56(84) bytes of data.
64 bytes from 172.16.86.2: icmp_seq=1 ttl=64 time=0.60 ms
This gives the host its own macvlan endpoint on the parent — the ip link ... type macvlan syntax is the kernel’s, documented in the ip-link(8) manual, and it matches Docker’s documented “create a macvlan interface on the host with the same parent interface” remedy. Tear it down with sudo ip link del mac0.
When macvlan is the wrong tool
Docker’s own considerations section is refreshingly honest:
- IP exhaustion and “VLAN spread” — an inappropriately large number of unique MAC addresses can degrade your network. Every container is one more MAC for your switches to track.
- Cloud networks usually block it. If you can’t get promiscuous-mode-friendly gear, you can’t use macvlan.
- The built-in alternatives may be better long-term: bridge for a single host, overlay for multiple hosts. Reach for macvlan only when the network must see real MAC addresses.
- Desktop and rootless are out — this is a Linux-engine feature only.
The bottom line
A macvlan network is one command: docker network create -d macvlan --subnet ... --gateway ... -o parent=eth0, after confirming the platform (Linux, kernel 4.0+, non-rootless, non-cloud-blocked) and the parent interface. Containers then appear on your LAN as physical peers with their own MACs — verifiable with docker inspect, ip addr, and a ping from a genuinely remote host. Budget for the two documented surprises: the host itself can’t reach macvlan containers without a workaround, and every container costs a MAC address somewhere in your switching fabric. When those constraints don’t apply, nothing else in Docker gives you containers that are indistinguishable from real machines.