If you have edited /etc/network/interfaces on Debian or ifcfg files on older Red Hat systems, Ubuntu’s network configuration looks unfamiliar: a directory of YAML files under /etc/netplan. That is Netplan, and once you understand what it is and is not, it is straightforward.

What Netplan is

Netplan is a translator. You describe the network you want in YAML, and Netplan generates configuration for one of two renderers:

Renderer	Used on	What runs the network
networkd	Ubuntu Server, cloud images	systemd-networkd
NetworkManager	Ubuntu Desktop	NetworkManager

Netplan itself does not stay running. It writes backend configuration at boot or when you apply changes, then gets out of the way. That is why troubleshooting often means looking at the backend too: networkctl status for networkd, or nmcli for NetworkManager, which our NetworkManager guide covers.

The files

Netplan reads every .yaml file in /etc/netplan (plus /run/netplan and /lib/netplan), in lexical order, and merges them. Later files override earlier ones for the same keys. A typical server has one file:

# /etc/netplan/50-cloud-init.yaml
network:
  version: 2
  ethernets:
    enp1s0:
      dhcp4: true

Indentation is significant and tabs are not allowed. Netplan also warns if the files are readable by other users, because they can contain Wi-Fi passwords, so keep them at mode 600.

A static IP

network:
  version: 2
  renderer: networkd
  ethernets:
    enp1s0:
      dhcp4: false
      addresses:
        - 192.168.1.50/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [1.1.1.1, 9.9.9.9]
        search: [lan]

Addresses are always in CIDR form; if prefix lengths are unfamiliar, our subnetting guide explains them. Use routes with to: default instead of the deprecated gateway4.

Find interface names with ip -brief link. Our Netplan config generator writes this YAML for you, including bridges and VLANs.

Bridges and VLANs

A bridge lets virtual machines appear directly on your LAN. The physical interface joins the bridge and the bridge gets the address:

network:
  version: 2
  ethernets:
    enp1s0:
      dhcp4: false
  bridges:
    br0:
      interfaces: [enp1s0]
      dhcp4: true

A VLAN is a tagged interface on top of a physical one:

  vlans:
    enp1s0.10:
      id: 10
      link: enp1s0
      addresses: [10.0.10.5/24]

Our VLANs and bridges guide explains when you need each.

Applying changes safely

sudo netplan generate   # check syntax and write backend config
sudo netplan try        # apply, roll back in 120 seconds unless confirmed
sudo netplan apply      # apply without a safety net

Make netplan try a habit, especially over SSH. If a typo in the gateway cuts you off, it reverts on its own and you reconnect after two minutes, instead of needing console access.

To see the result:

sudo netplan get                 # merged configuration from all files
netplan status                   # live interface state (recent releases)
ip -brief address && ip route    # what the kernel has

The cloud-init trap

On cloud and server images, cloud-init writes 50-cloud-init.yaml from the provider’s metadata, and on some setups regenerates it at boot, quietly undoing your edits. Two fixes:

1. Tell cloud-init to stop managing the network:

echo 'network: {config: disabled}' | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg

2. Or leave cloud-init alone and put your overrides in a later file, such as 90-local.yaml

Our cloud-init explainer covers what else it controls.

Netplan and the desktop

On Ubuntu Desktop, the renderer is NetworkManager, and since Ubuntu 23.10 changes made in Settings or with nmcli are written back as Netplan files, typically named 90-NetworkManager-*.yaml. You can manage a desktop entirely with the GUI or nmcli and let Netplan follow along; editing the YAML by hand is mainly a server habit.

Common mistakes

• Tabs or misaligned indentation: netplan generate reports the line
• Two files defining the same interface differently: check netplan get for the merged result
• Forgetting the prefix on an address (192.168.1.50 instead of 192.168.1.50/24)
• DHCP still on alongside a static address, giving the interface two addresses
• Using netplan apply remotely without a fallback

For the broader picture, our Linux networking basics and ip command guide cover the tools underneath.

Frequently Asked Questions

What is Netplan?

Netplan is a network configuration tool used by Ubuntu. You describe interfaces, addresses, routes, and DNS in YAML files under /etc/netplan, and Netplan generates configuration for a backend, either systemd-networkd or NetworkManager, which actually brings the network up.

Does Netplan replace NetworkManager?

No. Netplan is a configuration front end, not a network daemon. On Ubuntu Server it usually drives systemd-networkd; on Ubuntu Desktop it drives NetworkManager, and changes made in the desktop network settings are written back to Netplan files.

What is the difference between netplan apply and netplan try?

netplan apply activates the configuration immediately. netplan try applies it and waits, by default 120 seconds, for you to confirm; if you do not, for example because the change cut off your SSH session, it rolls back automatically. Use try on any remote machine.

Why do my Netplan changes disappear after a reboot?

On cloud images, cloud-init may regenerate 50-cloud-init.yaml at boot and override your edits. Either disable cloud-init network configuration with a file in /etc/cloud/cloud.cfg.d/ containing network: {config: disabled}, or put your settings in a file that sorts later, such as 90-local.yaml.

Should I still use gateway4?

No. gateway4 and gateway6 are deprecated. Use a routes entry with to: default and via: followed by the gateway address. Netplan prints a warning if it finds the old keys.

How do I see what Netplan actually applied?

Run sudo netplan get to see the merged YAML from all files, and netplan status on recent releases to see the live state of each interface. ip -brief address and ip route show what the kernel ended up with.