How to Set Static IP to Raspberry Pi Using NetworkManager

To set a static IP on a modern Raspberry Pi, you must use nmcli (NetworkManager). The legacy dhcpcd.conf method is fully deprecated in Raspberry Pi OS (Bookworm and Trixie). The exact command sequence targets the active connection profile name, not just the physical interface.

The Paradigm Shift: NetworkManager vs. dhcpcd

If you have been following older tutorials, you are likely looking for /etc/dhcpcd.conf. Stop looking. Starting with Raspberry Pi OS Bookworm (and continuing into 2026 releases), the Raspberry Pi Foundation migrated entirely to NetworkManager for all networking tasks. Editing legacy config files will result in your changes being ignored or overwritten on reboot.

Before writing commands, use this decision path to ensure a static IP is actually the correct architectural choice for your deployment.

Hardware Spec Sheet and Headless Debug Pinout

When configuring networking headlessly, a misconfigured static IP will lock you out of SSH. Before modifying network settings on a remote Pi, ensure you have physical access or a serial debug bridge wired up.

Target Board & Parts List

• Board: Raspberry Pi 5 (8GB) or Raspberry Pi 4 Model B (4GB+)
• OS: Raspberry Pi OS (64-bit, Bookworm or newer) - Lite or Desktop
• Power: Official 27W USB-C PD Power Supply (Critical: brownouts on the Pi 5 will cause the Ethernet PHY to drop packets during high CPU load)
• Cabling: Cat6 UTP or STP Ethernet cable

UART Recovery Pin Mapping

If your static IP configuration fails and you are locked out of SSH, connect a USB-to-TTL serial adapter (like a CP2102 or FT232RL) to these GPIO pins to access the console directly.

Terminal Settings: 115200 baud, 8 data bits, no parity, 1 stop bit (115200 8N1).

Step-by-Step: Setting a Static IP via nmcli

Follow these numbered steps to apply the configuration manually via SSH or serial console.

1. Identify the Connection Profile Name:
   nmcli connection show
   Look at the NAME column. For Ethernet, it is typically Wired connection 1. For Wi-Fi, it will be your SSID name. Do not confuse this with the DEVICE column (e.g., eth0).
2. Set the IP Addressing Method to Manual:
   nmcli con mod 'Wired connection 1' ipv4.method manual
3. Assign the Static IP and Subnet Mask:
   nmcli con mod 'Wired connection 1' ipv4.addresses 192.168.1.50/24
   Note: The CIDR notation (/24) is mandatory. Omitting it will cause the command to fail.
4. Define the Default Gateway:
   nmcli con mod 'Wired connection 1' ipv4.gateway 192.168.1.1
5. Set DNS Servers:
   nmcli con mod 'Wired connection 1' ipv4.dns '1.1.1.1 8.8.8.8'
6. Apply and Restart the Connection:
   nmcli con down 'Wired connection 1' && nmcli con up 'Wired connection 1'
   Warning: If you are doing this over SSH, your session will drop the moment you run this command if the new IP is on a different subnet than your current routing path.

The Automated Bash Script (Copy-Paste Ready)

For fleet deployments or repeatable builds, use this bash script. It includes error handling to verify the OS environment and the existence of the connection profile before applying changes.

#!/bin/bash
set -euo pipefail

# Target Board: Raspberry Pi 5 (8GB) / Raspberry Pi 4 Model B
# Target OS: Raspberry Pi OS (64-bit, Bookworm/Trixie) using NetworkManager
# Interface: Primary Ethernet Profile

CON_NAME='Wired connection 1'
STATIC_IP='192.168.1.50/24'
GATEWAY='192.168.1.1'
DNS='1.1.1.1,8.8.8.8'

# 1. Verify NetworkManager is the active manager
if ! command -v nmcli &> /dev/null; then
    echo 'FATAL: nmcli not found. Are you on an older Raspbian release using dhcpcd?'
    exit 1
fi

# 2. Verify the connection profile exists
if ! nmcli -t -f NAME con show | grep -q "^${CON_NAME}$"; then
    echo "FATAL: Connection profile '${CON_NAME}' not found."
    echo 'Available profiles:'
    nmcli -t -f NAME,TYPE,DEVICE con show
    exit 1
fi

echo "Applying static IP configuration to '${CON_NAME}'..."
nmcli con mod "${CON_NAME}" ipv4.method manual
nmcli con mod "${CON_NAME}" ipv4.addresses "${STATIC_IP}"
nmcli con mod "${CON_NAME}" ipv4.gateway "${GATEWAY}"
nmcli con mod "${CON_NAME}" ipv4.dns "${DNS}"

echo 'Restarting connection...'
nmcli con down "${CON_NAME}" && nmcli con up "${CON_NAME}"

echo 'Success. Verify with: ip -4 addr show eth0'

Troubleshooting: When the SSH Session Drops

Network configuration on headless boards is unforgiving. If you lose connectivity, here is how to diagnose the failure.

Exact Error String: Error: unknown connection 'eth0'.

This is the most common error users encounter when transitioning from legacy networking to NetworkManager.

• Cause 1 (Most Likely): You typed the physical interface name (eth0) instead of the NetworkManager profile name (Wired connection 1). nmcli con mod operates on profiles, not raw interfaces.
• Cause 2: The Ethernet cable was unplugged during the initial OS boot. NetworkManager delays creating the 'Wired connection 1' profile until a physical link is detected on the RJ45 port.
• Fix: Plug in the cable, wait 5 seconds for the link LEDs to illuminate, run nmcli connection show, and copy the exact string from the NAME column.

The First Three Things to Check When It Fails

If the script runs without errors but you cannot ping the Pi or SSH into it, check these three variables immediately via your UART serial console:

1. Subnet Mask Omission: Did you type 192.168.1.50 instead of 192.168.1.50/24? Without the CIDR mask, NetworkManager assumes a /32 host route, meaning the Pi will refuse to talk to any device outside its exact IP address, including your gateway.
2. Gateway Reachability: Run ping -c 3 192.168.1.1. If it fails, your static IP is on the wrong VLAN, or your router's DHCP pool overlaps with your chosen static IP, causing an ARP conflict.
3. Interface State: Run nmcli device status. If eth0 shows as disconnected rather than connected, the profile configuration has a syntax error preventing the handshake. Check journalctl -u NetworkManager -n 50 for the exact rejection reason.

Extending and Simplifying the Build

Once your baseline static IP is stable, you can adapt the setup for more complex embedded topologies.

How to Simplify: Router-Side MAC Binding

If your Pi is permanently installed on a managed network, simplify your maintenance burden by reverting the Pi to DHCP (nmcli con mod 'Wired connection 1' ipv4.method auto) and setting a static DHCP reservation in your router (e.g., pfSense, UniFi, or OpenWrt) binding the Pi's MAC address to your desired IP. This keeps the Pi's OS configuration generic and portable.

How to Extend: Adding a Secondary IP or VLAN

For industrial IoT gateways that must talk to both a local PLC network and an upstream WAN, you can append secondary addresses or tag VLANs directly via nmcli.

• Secondary IP: nmcli con mod 'Wired connection 1' +ipv4.addresses 10.0.0.5/24 (Note the + sign, which appends rather than overwrites).
• VLAN Tagging: Create a virtual interface for a specific VLAN tag:
  nmcli con add type vlan con-name 'VLAN-20' ifname 'eth0.20' dev 'eth0' id 20 ipv4.method manual ipv4.addresses 192.168.20.5/24

By mastering nmcli and understanding the underlying Debian NetworkManager architecture, you eliminate the guesswork from headless Raspberry Pi deployments and ensure your embedded nodes survive reboots, OS upgrades, and network topology changes.