Inspect Live Network State with netplan status

You will use netplan status to see the network state that is currently running, narrow the view to one interface, export data as JSON or YAML, and compare the live state with Netplan's YAML definitions. Allow about ten minutes. The commands are read-only, but the status query can try to start systemd-networkd when that service is not masked, so do not use the first command blindly on a production host where service activation needs a change window.

This guide describes Netplan from netplan.io version 1.1.2-8ubuntu1~24.04.3, installed on Ubuntu 24.04 here. Your output will contain different interface names, addresses and routes. Do not copy those host-specific values into a configuration file.

1. Check the installed command

Start with help and package information. These are ordinary, read-only commands and normally need no elevated privileges:

$ command -v netplan
/usr/sbin/netplan
$ dpkg-query -W -f='${Package} ${Version}\n' netplan.io
netplan.io 1.1.2-8ubuntu1~24.04.3
$ netplan status --help
usage: /usr/sbin/netplan status [-h] [--debug] [-a] [-v] [-f FORMAT] [--diff]
                                [--diff-only] [--root-dir ROOT_DIR]
                                [ifname]

The command is a subcommand of netplan; there is no separate netplan-status executable to invoke. The optional final argument is an interface name such as enp1s0 or eno1.

2. Read the normal human-readable status

Run the command without an interface to see the online state, DNS information and the interfaces that Netplan can obtain from its current data source:

$ netplan status
     Online state: online
    DNS Addresses: 127.0.0.53 (stub)
       DNS Search: .

●  2: enp1s0 ethernet UP (networkd: enp1s0)
      MAC Address: 52:54:00:12:34:56
        Addresses: 192.0.2.25/24
           Routes: default via 192.0.2.1 (static)

The exact layout depends on the host. Look for the interface's administrative and operational states, addresses, DNS addresses, routes and, for bridges, attached interfaces. An interface shown as unmanaged is still visible, but it is not being managed by the reported Netplan backend.

Checkpoint: if the command exits successfully and you can identify the expected interface, you have a usable live-state snapshot. This command does not apply YAML, generate configuration, bring links up or down, or repair a route.

3. Focus on one interface

First list likely names without changing anything:

$ ip -brief link
lo               UNKNOWN        00:00:00:00:00:00
enp1s0           UP             52:54:00:12:34:56
$ netplan status enp1s0

Replace enp1s0 with an exact name from your machine. The focused result still includes the host's online and DNS summary, followed by the selected interface. If Netplan says the interface does not exist, check spelling with ip -brief link; do not guess a name from a YAML file.

By default, inactive interfaces can be hidden. Add --all when you need the complete interface data:

$ netplan status --all
$ netplan status --all enp1s0

The second form is useful when you want the selected interface even while also making the inclusion rule explicit. It does not activate the interface.

4. Export data for a script

Use --format json or --format yaml when another tool needs stable, machine-readable output. The short form is -f:

$ netplan status --format json > /tmp/netplan-status.json
$ python3 -m json.tool /tmp/netplan-status.json > /dev/null
$ netplan status -f yaml > /tmp/netplan-status.yaml
$ test -s /tmp/netplan-status.yaml && echo 'YAML snapshot written'
YAML snapshot written

Redirection writes files under /tmp in this example and does not alter networking. JSON keys include global state and interface names; interface records can contain administrative state, operational state, addresses, routes, DNS data and backend details. Treat addresses and MAC addresses as host data rather than fixed schema examples. Remove these temporary snapshots when they are no longer needed, especially if they reveal internal addresses:

$ rm -- /tmp/netplan-status.json /tmp/netplan-status.yaml

That removal is irreversible. Skip it if you need the snapshots for an incident record, and store them according to your normal data-retention rules.

5. Compare live state with Netplan YAML

Use --diff to compare current system configuration with the network definitions in the YAML files. The comparison covers addresses, routes, MAC addresses, DNS addresses, search domains and missing interfaces:

$ netplan status --diff
--- system
+++ netplan
... lines depend on the host ...

A plus sign marks data present only in the system, while a minus sign marks data present only in Netplan. The terminal may use colour, but read the signs rather than relying on colour. This is an analysis command: it does not reconcile the two states and does not apply the YAML.

For a script or a review that only needs mismatches, use --diff-only:

$ netplan status --diff-only
No differences were reported.

The exact no-difference output can vary by release and host. A permission error is different from an empty diff: it means the process could not read one or more configuration files. Check access first:

$ find /etc/netplan -maxdepth 1 -type f -readable -print
$ namei -l /etc/netplan

If policy allows it, an administrator can repeat the read-only comparison with elevated privileges:

$ sudo netplan status --diff-only

Review the command before entering a password. Do not use sudo netplan apply as a response to a diff unless you have separately reviewed and tested the YAML. Applying network configuration can disconnect your session, and this guide intentionally does not change that state.

6. Inspect an alternate YAML root

--root-dir makes Netplan read YAML files from another root instead of /. This is useful when examining a mounted system or a staged filesystem. The argument is a directory, not the path to one YAML file:

$ sudo netplan status --root-dir /mnt/target --diff-only

This still queries the running system for current state while reading definitions below /mnt/target. It does not chroot into that tree, and it does not apply its configuration. Confirm the mount and directory before running the comparison:

$ mountpoint /mnt/target
$ find /mnt/target/etc/netplan -maxdepth 1 -type f -print

If the directory is not the root of the system you mean to inspect, stop and correct the path. A misleading diff is worse than a failed one.

7. Add detail only when needed

--verbose adds extra information, and --debug prints diagnostic messages during processing. Use them when a normal query does not explain a result:

$ netplan status --verbose enp1s0
$ netplan --debug status enp1s0 2> /tmp/netplan-status-debug.log
$ sed -n '1,120p' /tmp/netplan-status-debug.log

Debug output can include interface and configuration details. Treat the log as operational data and remove it when you are done:

$ rm -- /tmp/netplan-status-debug.log

If status tries to start systemd-networkd, remember that this is a service action even though the command is intended for inspection. On a machine that uses NetworkManager or another renderer, check the host's design and the service state before relying on the result. A masked systemd-networkd prevents Netplan from starting it, but that can also leave this data source unavailable.