Skip to content

Raspberry Pi NetworkManager and nmcli Guide

Raspberry Pi OS Trixie uses NetworkManager to manage normal Ethernet and Wi-Fi connections. Use nmcli for repeatable commands, nmtui for an interactive terminal interface, or Control Centre on the desktop. Avoid editing dhcpcd.conf or a global wpa_supplicant.conf by following instructions written for older releases.

Command quick reference

Task Command
Overall state nmcli general status
Device state nmcli device status
Active profiles nmcli connection show --active
All profiles nmcli connection show
IP addresses ip -brief address
Routes ip route and ip -6 route
DNS resolvectl status
Wi-Fi scan nmcli device wifi list
Interactive configuration sudo nmtui
NetworkManager logs journalctl -b -u NetworkManager --no-pager

For first boot and remote-access choices, start with the headless and networking hub.

Identify interfaces and profiles

Run these before changing anything:

1
2
3
4
5
nmcli general status
nmcli device status
nmcli connection show
ip -brief address
ip route

NetworkManager connection profiles have names such as Wired connection 1; devices have names such as eth0 or wlan0. Commands that modify a connection usually require the profile name, not the device name.

Show the profile attached to each active device:

1
nmcli -f NAME,UUID,TYPE,DEVICE connection show --active

Do not assume that every system uses eth0 and wlan0. Predictable interface naming, USB adapters, and Compute Module hardware can produce other names.

Connect to Wi-Fi

Enable the radio and scan:

1
2
nmcli radio wifi on
nmcli device wifi list

Use --ask so the password is not placed directly in shell history:

1
sudo nmcli --ask device wifi connect "YOUR-SSID"

Confirm the active profile:

1
2
nmcli connection show --active
nmcli -f GENERAL,IP4,IP6 device show wlan0

For a hidden network:

1
sudo nmcli --ask device wifi connect "YOUR-SSID" hidden yes

Set the correct Wi-Fi country during Imager setup or through the supported Raspberry Pi configuration interface. The regulatory domain affects legal channels and radio behaviour.

Manage saved Wi-Fi profiles

List profiles:

1
nmcli -f NAME,TYPE,DEVICE,AUTOCONNECT connection show

Prefer one network over another with autoconnect priority:

1
2
sudo nmcli connection modify "Preferred Wi-Fi" connection.autoconnect-priority 20
sudo nmcli connection modify "Fallback Wi-Fi" connection.autoconnect-priority 10

Remove an obsolete profile only after confirming its exact name:

1
sudo nmcli connection delete "Old Wi-Fi"

View a profile without printing stored secrets:

1
nmcli --show-secrets no connection show "Preferred Wi-Fi"

Ethernet with DHCP

Most networks supply an address, route, and DNS through DHCP. To return a profile to automatic IPv4:

1
2
3
4
5
sudo nmcli connection modify "Wired connection 1" \
  ipv4.method auto \
  ipv4.addresses "" \
  ipv4.gateway "" \
  ipv4.dns ""

Apply it only when you have local or alternate access:

1
2
sudo nmcli connection down "Wired connection 1"
sudo nmcli connection up "Wired connection 1"

Cycling the profile disconnects an SSH session using it.

Static IPv4 with NetworkManager

When you control the router, prefer a DHCP reservation. Use a device-side static address when the deployment requires it and the address has been reserved in the network plan.

Example values:

1
2
3
Address: 192.168.10.50/24
Gateway: 192.168.10.1
DNS: 192.168.10.1 and 1.1.1.1

Apply them to the actual profile name:

1
2
3
4
5
sudo nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses "192.168.10.50/24" \
  ipv4.gateway "192.168.10.1" \
  ipv4.dns "192.168.10.1 1.1.1.1"

Inspect before activation:

1
nmcli --show-secrets no connection show "Wired connection 1"

Verify that the address is not already in use and is not available to another DHCP client. Address-conflict checks are network-specific; coordinate with the administrator rather than relying on one ping result.

Make a remote change safely

Changing the active profile over SSH can lock you out. Before activation:

  1. Keep the current SSH session open.
  2. Prepare Ethernet, USB Gadget, serial, or local-console recovery.
  3. Record the original profile values.
  4. Schedule an automatic rollback.
  5. Apply one change.
  6. Test from a second client session.
  7. Cancel the rollback only after verification.

Create a profile clone for a reversible experiment:

1
2
3
4
5
6
sudo nmcli connection clone "Wired connection 1" "Wired test static"
sudo nmcli connection modify "Wired test static" \
  ipv4.method manual \
  ipv4.addresses "192.168.10.50/24" \
  ipv4.gateway "192.168.10.1" \
  ipv4.dns "192.168.10.1"

A clone reduces accidental damage to the known-good profile, but activating it can still disconnect you.

IPv6

Do not disable IPv6 as a generic troubleshooting step. Inspect it independently:

1
2
3
ip -6 address
ip -6 route
nmcli -f IP6 device show eth0

If a deployment intentionally uses no IPv6, document that policy and test the applications before disabling it on a profile.

DNS diagnostics

Check configured resolvers and per-interface domains:

1
2
3
resolvectl status
resolvectl query raspberrypi.com
getent ahosts raspberrypi.com

Test layers separately:

1
2
3
4
5
6
7
8
9
# Gateway reachability; replace with the actual default route
ip route
ping -c 3 192.168.10.1

# Internet routing without relying on DNS
ping -c 3 1.1.1.1

# DNS resolution
getent hosts raspberrypi.com

If an IP works but a hostname does not, investigate DNS. If the gateway cannot be reached, changing public DNS will not fix the link or route.

Route selection and metrics

Show routes:

1
2
ip route
ip route get 1.1.1.1

When Ethernet and Wi-Fi are both active, route metrics determine preference. Set a lower metric on the preferred profile:

1
2
sudo nmcli connection modify "Wired connection 1" ipv4.route-metric 100
sudo nmcli connection modify "Preferred Wi-Fi" ipv4.route-metric 600

Reconnect during a maintenance window, then confirm with ip route get.

Create a Wi-Fi hotspot

For a quick routed hotspot:

1
2
3
4
5
sudo nmcli device wifi hotspot \
  ifname wlan0 \
  con-name "Pi Hotspot" \
  ssid "Pi-Lab" \
  password "replace-with-a-unique-passphrase"

This command places a credential in shell history. Prefer an interactive or protected provisioning workflow on shared systems. For routing models, client isolation, bridge mode, and recovery, see Raspberry Pi Wi-Fi access point.

USB networking

Current Trixie images support an official USB Gadget workflow on compatible boards. It presents the Pi as a USB Ethernet device and is useful when no LAN is available.

See SSH over USB with rpi-usb-gadget. Do not confuse USB Ethernet with USB mass-storage emulation.

Hostname and local discovery

1
2
hostnamectl hostname
sudo hostnamectl hostname pi-lab-01

On networks with mDNS support:

1
ssh your-user@pi-lab-01.local

Managed networks can block multicast discovery. Use DHCP/DNS inventory rather than assuming .local works everywhere.

Ethernet:

1
2
3
sudo apt install -y ethtool
ethtool eth0
ip -s link show eth0

Wi-Fi:

1
2
3
iw dev wlan0 link
nmcli -f IN-USE,SSID,SIGNAL,RATE,SECURITY device wifi list
ip -s link show wlan0

Packet loss, retries, duplex negotiation, low signal, interference, cable quality, and power can all affect throughput. Measure before changing MTU, offload, or radio settings.

Firewall inspection

Raspberry Pi OS networking and firewall policy are separate layers. Inspect the active ruleset:

1
2
sudo nft list ruleset
sudo ss -lntup

If using UFW:

1
sudo ufw status verbose

Allow administration from a trusted network before enabling a deny-by-default policy. Keep the current SSH session open while testing a new session.

Diagnostic bundle

The following command collection avoids printing Wi-Fi passwords:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  date --iso-8601=seconds
  hostnamectl
  nmcli general status
  nmcli device status
  nmcli connection show --active
  ip -brief address
  ip route
  ip -6 route
  resolvectl status
  systemctl --failed
} | tee network-diagnostics.txt

Review logs for secrets, public addresses, hostnames, and organisation details before sharing them.

Troubleshooting table

Symptom First checks Likely layer
Interface DOWN Cable, radio, rfkill, ip -brief link Physical/link
No IP address Active profile, DHCP logs, address plan Network configuration
Gateway unreachable Prefix, route, VLAN, Wi-Fi association Local network
IP works, names fail resolvectl status, DNS query DNS
SSH refused systemctl status ssh, listening sockets Service
SSH times out Route, firewall, wrong address Path/firewall
Intermittent disconnects Power, signal, cable, kernel log Physical/power
Wrong interface used ip route get, route metrics Routing policy

FAQ

Does Raspberry Pi OS Trixie use NetworkManager?

Yes for normal desktop, Ethernet, and Wi-Fi profile management. Use nmcli, nmtui, or Control Centre rather than old dhcpcd.conf instructions.

Is a static IP required for a server?

No. A DHCP reservation often provides stability with less risk of conflicts. A device-side static profile is useful when the network plan requires it.

Why does editing /etc/resolv.conf not persist?

It is normally managed by the active networking and resolver stack. Configure DNS on the NetworkManager profile instead of overwriting generated state.

Should I turn off Wi-Fi when Ethernet connects?

Not necessarily. Route metrics can prefer Ethernet while retaining Wi-Fi as a fallback. Test failure behaviour before relying on automatic failover.

How can I avoid losing SSH during a change?

Use an alternate connection such as USB Gadget, clone the profile, schedule rollback, keep the old session open, and verify from a second terminal.