Macvlan Networks: Use Cases and Limitations

1. What a macvlan network technically is

A macvlan network assigns every attached container its own virtual MAC address on top of the host's physical network interface. From the perspective of the rest of the LAN, the container then appears as a standalone physical device with its own Ethernet address, not as a process sharing a host. This fundamentally distinguishes a macvlan network from a bridge network, where all containers stay hidden behind the host's IP address through NAT.

Technically, Docker uses the Linux kernel's macvlan driver for this, which creates several virtual interfaces, each with its own MAC address, on top of one physical parent interface. Each of these virtual interfaces is assigned to a container and gets a regular IP address from the physical LAN subnet, either via DHCP or a fixed assignment. This makes a macvlan network the most direct way to make a container appear as a full device on the existing network, without needing port forwarding or NAT rules.

2. When macvlan is the right choice

The classic use case for a macvlan network is migrating a legacy application into a container that absolutely needs a fixed, own IP address on the company network, because other systems expect exactly that IP in their configuration. Instead of rewriting the application to work with port mapping, the container simply gets the expected IP address assigned through macvlan and fits seamlessly into existing firewall rules and monitoring systems.

A second common use case is network monitoring and security tooling that needs direct access to layer 2 information such as ARP requests or broadcast traffic, which would not be visible behind a NAT-based bridge. Multicast applications and device simulations, where a container is meant to impersonate a specific physical device on the network, also benefit from a macvlan network because it provides genuine layer 2 visibility instead of the abstracted view of a bridge network.

3. Creating a macvlan network

Creating a macvlan network requires specifying the physical parent interface, that is, the host's network card that the virtual interfaces are bound to. In addition, the subnet and gateway of the physical LAN must be provided so Docker knows which address range the containers move in. Unlike a bridge network, Docker does not invent its own subnet here but uses exactly the existing network of the physical infrastructure.

It is important that the chosen parent interface is actually connected to the desired LAN segment, otherwise containers do get an IP address but end up isolated in the wrong network segment. On servers with multiple network cards or VLAN trunks, the correct interface has to be selected explicitly, which in practice is the most common stumbling block when setting up a macvlan network for the first time.

# Identify the physical parent interface first
ip link show

# Create a macvlan network bound to the physical interface eth0
docker network create -d macvlan \
  --subnet 192.168.10.0/24 \
  --gateway 192.168.10.1 \
  -o parent=eth0 \
  lan-macvlan

# Inspect the network to confirm subnet and parent interface
docker network inspect lan-macvlan

4. Starting a container with its own LAN IP

Once the macvlan network exists, a container is simply started with --network and optionally a fixed IP address. The container is then directly reachable from the entire LAN under that address, without ever having to publish a port on the Docker host. Other devices on the network see the container as a standalone network participant with its own MAC address, which becomes clearly visible in ARP requests and network scans.

For DNS entries in the company's internal name resolution, this means the container can be registered like a regular device in the corporate DNS server, with a fixed IP address and its own hostname. That is a clear difference from a bridge network, where the container would only be reachable from outside through the host and its ports. A macvlan network completes the container-to-device transformation on the network, instead of hiding it behind a NAT layer.

# Start a container with a fixed LAN IP on the macvlan network
docker run -d --name legacy-app \
  --network lan-macvlan \
  --ip 192.168.10.50 \
  --mac-address 02:42:c0:a8:0a:32 \
  legacy-app:latest

# From another device on the LAN, the container answers like a real host
ping -c 2 192.168.10.50
arp -a | grep 192.168.10.50

5. The promiscuous mode problem with host communication

The best known limitation of a macvlan network concerns direct communication between the Docker host itself and containers running on the same parent interface. By default, the Linux kernel prevents the host's network stack from sending packets to macvlan interfaces derived from the same physical interface as the host. In practice this means the host cannot ping containers in its own macvlan network, even though every other device on the LAN can do so without issue.

The common solution is to create an additional macvlan sub-interface directly on the host, bound to the same physical network card but acting as a separate network participant. Through this sub-interface, the host can then communicate with its own containers in the macvlan network. This extra configuration step is often overlooked and leads to confusion when health checks from the host fail while the container itself works correctly and is reachable from outside.

# Create a macvlan sub-interface on the host to talk to its own containers
ip link add macvlan-shim link eth0 type macvlan mode bridge
ip addr add 192.168.10.5/24 dev macvlan-shim
ip link set macvlan-shim up

# Route traffic to the macvlan subnet through the shim interface
ip route add 192.168.10.0/24 dev macvlan-shim

# The host can now reach containers in the macvlan network
ping -c 2 192.168.10.50

6. Mapping VLANs with macvlan sub-interfaces

In environments with VLAN segmentation, a macvlan network can be bound directly to an 802.1Q sub-interface instead of to the physical network card itself. To do this, a VLAN sub-interface carrying the corresponding VLAN tag is first created on the host, and this sub-interface is then used as the parent interface for the macvlan network. This lets containers be assigned to a specific VLAN, without the entire trunk traffic having to be visible on the host.

This is especially valuable in environments where different customer environments or security zones are separated from each other by VLANs. A Docker host can run several macvlan networks in parallel this way, each bound to its own VLAN sub-interface, and assign containers to the matching segment. Docker itself does not need to know anything about VLAN tagging; the entire encapsulation already happens at the kernel level before the traffic even reaches the macvlan driver.

# Create a VLAN sub-interface for VLAN ID 20 on eth0
ip link add link eth0 name eth0.20 type vlan id 20
ip link set eth0.20 up

# Bind a macvlan network to the VLAN sub-interface instead of eth0
docker network create -d macvlan \
  --subnet 192.168.20.0/24 \
  --gateway 192.168.20.1 \
  -o parent=eth0.20 \
  vlan20-macvlan

7. Security and network segmentation with macvlan

A macvlan network puts containers on the same visibility level as physical devices on the LAN, which has both benefits and drawbacks for security. The benefit: existing network firewalls, IDS systems and access control lists apply directly to container traffic without Docker-specific NAT rules getting in the way. The drawback: a container in a macvlan network is just as visible across the entire LAN as any other device, which removes the isolation benefits of a bridge network.

Anyone running a macvlan network in production should consistently use physical network segmentation, for example through VLANs, to avoid unintentionally placing containers in the same segment as sensitive internal systems. Since Docker itself does not enforce any firewall rules between containers in the same macvlan segment, the entire responsibility for segmentation lies with the physical network infrastructure, not with Docker.

8. Limitations of macvlan in practice

The biggest practical limitation of a macvlan network shows up in cloud environments. Most cloud providers filter traffic with unknown MAC addresses on their virtual switches to prevent spoofing, which makes a macvlan network effectively unusable in such environments unless the provider allows an explicit exception. This largely restricts macvlan to on-premise environments with physical network access.

Portability suffers too: a Compose setup with a macvlan network cannot simply be copied to another machine, because the parent interface, subnet and gateway are configured per host. The promiscuous mode workaround from section five adds further maintenance overhead. In practice, a macvlan network therefore remains the exception for specific legacy and monitoring requirements, while the majority of container workloads stay significantly simpler and more portable with a regular bridge network.

# Quick check whether macvlan traffic actually leaves the host
# (run from another device on the same LAN segment)
tcpdump -i eth0 -n host 192.168.10.50

# List all macvlan networks currently configured on this host
docker network ls --filter driver=macvlan

# Remove a macvlan network no longer needed (detach containers first)
docker network rm lan-macvlan

9. Macvlan, bridge and host network compared

The following table compares the three most important Docker network drivers for single host scenarios and shows what a macvlan network is actually suited for compared to bridge and host networking.

This comparison makes clear that a macvlan network is a targeted special-purpose solution, not a general recommendation for new projects. Anyone without the requirements mentioned for LAN visibility is almost always better off with a regular bridge network that is simpler and more portable.

10. Summary

A macvlan network gives Docker containers a real IP and MAC address visible on the physical LAN, with no port mapping through the host at all. This solves concrete problems for legacy applications with hardcoded IP expectations, for network monitoring at layer 2, and for mapping VLAN segments through macvlan sub-interfaces. The best known limitation is the missing direct communication between host and container in the same macvlan network, which requires an additional sub-interface workaround.

In cloud environments, a macvlan network usually fails due to MAC address filtering on virtual switches, which restricts practical use to on-premise infrastructure with physical network access. Anyone without one of the special requirements mentioned should stick with a regular bridge network, which is more portable, easier to maintain and available in every environment. Macvlan therefore remains a targeted tool for specific networking requirements, not a general recommendation for new container projects.

11. FAQ: Macvlan Networks