Skip to content

Raspberry Pi NetworkManager: nmcli Setup and Troubleshooting

If networking eventually works but boot is slow, use the NetworkManager wait-online diagnosis guide to inspect startup dependencies and profile activation delays.

Raspberry Pi OS Bookworm and Trixie use 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. Check the active manager with nmcli general status; older installations may differ. See the official Raspberry Pi networking documentation.

Quick answer: Raspberry Pi network not working

Run nmcli device status, ip route, and resolvectl status. If the interface is disconnected, activate the correct NetworkManager profile. If an IP address works but a hostname does not, fix DNS. If neither the gateway nor an IP address responds, investigate the Wi-Fi/Ethernet link and route before changing DNS.

Diagnose the failure layer first

Symptom Check first Likely layer
Wi-Fi SSID is missing nmcli device wifi list and WLAN country Radio, regulatory domain, signal, or channel
Device says disconnected nmcli device status and saved profiles NetworkManager profile or authentication
Address starts with 169.254 nmcli -f IP4 device show DHCP did not provide an address
Gateway works, 1.1.1.1 fails ip route and router uplink Default route or upstream internet
1.1.1.1 works, names fail resolvectl status DNS configuration
SSH stopped after a change Local console plus profile clone/rollback Active profile was replaced or disconnected

Collect the commands in the quick reference before restarting NetworkManager. Restarting the service can terminate SSH and erase useful transient state.

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.

When a NetworkManager update fails

For an error-by-error recovery workflow, use NetworkManager update failure and APT repair. It covers interrupted dpkg operations, dependency-repair previews, disk space, and protecting remote access.

If sudo apt update or an upgrade reports a network-manager error, first distinguish a broken network connection from a package-management failure. Record the exact error before changing connection profiles or removing packages, especially when connected over SSH.

1
2
3
4
5
6
7
8
9
cat /etc/os-release
nmcli general status
nmcli device status
ip route
resolvectl status
df -h /
sudo apt update
apt-cache policy network-manager
apt-mark showhold
  • Name-resolution or connection timeout: Test the gateway, an IP address, and a hostname separately using DNS diagnostics. Fix the connection before retrying APT.
  • Repository or release mismatch: Inspect the APT error and configured sources. Do not combine Bookworm and Trixie repositories to make a package install. For a major release change, follow the Trixie migration guide and the official Raspberry Pi OS update guidance.
  • Held package, insufficient space, or interrupted installation: Resolve the reported condition before retrying the update. Do not force-remove NetworkManager from a Pi you administer remotely; that could disconnect it.

For routine updates within the same Raspberry Pi OS release, run sudo apt full-upgrade only after sudo apt update succeeds and you have confirmed adequate free space. A major Bookworm-to-Trixie migration is a separate task, not a repair for a failed package update.

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

To identify which process initiates short-lived outgoing TCP connections, use the tcpconnect-bpfcc guide for Raspberry Pi. Unlike a socket snapshot, it traces new connection activity while it is running.

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.

Donate