How to Make Raspberry Pi IP Static on Bookworm (NetworkManager Guide)

If you are trying to make Raspberry Pi IP static and your search results tell you to edit /etc/dhcpcd.conf, stop. You are following outdated advice. With the release of Raspberry Pi OS 'Bookworm' (and shipping natively on the Raspberry Pi 5), the underlying network stack shifted entirely from dhcpcd to NetworkManager. Editing deprecated config files will result in a Pi that ignores your settings or drops off your network upon reboot.

The direct answer: To assign a static IP on modern Pi OS, use the nmcli (NetworkManager Command Line Interface) tool to modify the active connection profile. For a standard home lab setup, you will target the 'Wired connection 1' profile, assign an IPv4 address with CIDR notation (e.g., 192.168.1.50/24), set the gateway, and define manual DNS servers.

The Bookworm Shift: Why Old Static IP Tutorials Fail

For nearly a decade, Raspberry Pi users relied on dhcpcd to handle DHCP requests and static IP assignments. However, as enterprise Linux distributions standardized on NetworkManager, the Raspberry Pi Foundation followed suit to improve Wi-Fi roaming, VPN integration, and cellular modem support. According to the Raspberry Pi Official Configuration Docs, dhcpcd is no longer installed by default on Bookworm-based images.

If you attempt to install dhcpcd manually to force the old workflow, you will create a race condition where both NetworkManager and dhcpcd fight for control of the eth0 interface, leading to intermittent packet loss and SSH timeouts. The modern, supported method relies on nmcli, which interacts directly with the NetworkManager daemon via D-Bus.

Hardware & Network Interface Spec Sheet

Before writing commands, you must understand how NetworkManager maps physical interfaces to logical connection profiles. NetworkManager does not configure 'eth0'; it configures a profile that is bound to eth0.

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

This procedure targets the Raspberry Pi 4 and Pi 5 running Raspberry Pi OS Bookworm (or later) via the wired Ethernet connection.

1. Identify your active connection profile.
   Run nmcli con show --active. Look under the 'NAME' column. For Ethernet, it is usually Wired connection 1.
2. Assign the static IPv4 address and subnet.
   sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.50/24
3. Set the default gateway (your router's IP).
   sudo nmcli con mod "Wired connection 1" ipv4.gateway 192.168.1.1
4. Configure manual DNS servers to bypass router DNS hijacking.
   sudo nmcli con mod "Wired connection 1" ipv4.dns "1.1.1.1 8.8.8.8"
5. Switch the IPv4 method from DHCP to manual.
   sudo nmcli con mod "Wired connection 1" ipv4.method manual
6. Restart the connection to apply changes.
   sudo nmcli con up "Wired connection 1"

Verify the build: Run ip -4 addr show eth0. You should see inet 192.168.1.50/24. Ping an external domain: ping -c 3 google.com to confirm routing and DNS are functional.

Automated Provisioning Script with Error Handling

When deploying headless Pis for IoT sensor nodes or Home Assistant servers, typing these commands manually is prone to typos. Below is a complete, compilable Bash script that safely applies a static IP, validates the inputs, and includes error handling to prevent locking you out of a headless SSH session.

#!/bin/bash
# Target: Raspberry Pi OS Bookworm (NetworkManager)
# Purpose: Safely assign a static IP to the primary wired interface

set -euo pipefail

# --- Configuration Variables ---
CON_NAME="Wired connection 1"
STATIC_IP="192.168.1.50/24"
GATEWAY="192.168.1.1"
DNS_SERVERS="1.1.1.1,8.8.8.8"
INTERFACE="eth0"

# --- Error Handling Trap ---
cleanup() {
  if [ $? -ne 0 ]; then
    echo "[ERROR] Static IP assignment failed. Reverting to DHCP to prevent lockout..."
    sudo nmcli con mod "$CON_NAME" ipv4.method auto
    sudo nmcli con up "$CON_NAME"
    echo "[INFO] Reverted to DHCP. Check your CIDR notation and gateway."
  fi
}
trap cleanup EXIT

# --- Pre-flight Checks ---
if ! command -v nmcli &> /dev/null; then
  echo "[FATAL] nmcli not found. Are you running an older OS with dhcpcd?"
  exit 1
fi

if ! ip link show "$INTERFACE" &> /dev/null; then
  echo "[FATAL] Interface $INTERFACE does not exist. Check physical cabling."
  exit 1
fi

# --- Apply NetworkManager Configuration ---
echo "[INFO] Modifying profile: $CON_NAME"
sudo nmcli con mod "$CON_NAME" \
  ipv4.addresses "$STATIC_IP" \
  ipv4.gateway "$GATEWAY" \
  ipv4.dns "$DNS_SERVERS" \
  ipv4.method manual

echo "[INFO] Restarting connection..."
sudo nmcli con up "$CON_NAME"

# --- Verification ---
sleep 2
if ip -4 addr show "$INTERFACE" | grep -q "${STATIC_IP%/*}"; then
  echo "[SUCCESS] Static IP $STATIC_IP successfully applied to $INTERFACE."
  # Disable the trap since we succeeded
  trap - EXIT
else
  echo "[ERROR] IP address not detected on interface after restart."
  exit 1
fi

How to extend or simplify: To simplify headless deployments, save this script as set-static-ip.sh on the boot partition of your MicroSD card, and trigger it via a systemd service on first boot. To extend it for Wi-Fi, change CON_NAME to your SSID and INTERFACE to wlan0.

Troubleshooting: Ranked Causes for Network Failures

If your Pi drops offline after applying these settings, do not panic. Here are the first three things to check when it fails, followed by exact error strings.

1. Verify NetworkManager is active: Run systemctl status NetworkManager. If it's dead, your OS image might be corrupted or you are on a legacy Lite build that stripped it out.
2. Confirm the Profile Name: Users frequently type nmcli con mod eth0. eth0 is the hardware interface, not the connection profile. Run nmcli con show to get the exact string (usually 'Wired connection 1').
3. Check for IP Conflicts: If another device already holds 192.168.1.50, the router will drop the Pi's ARP requests. Use arping -D -I eth0 192.168.1.50 from another PC to verify the IP is truly free.

Exact Error Strings and Fixes

Exact Error String	Root Cause	The Fix
Error: unknown connection 'eth0'	Confusing the physical interface name with the NetworkManager profile name.	Use nmcli con show and replace 'eth0' with 'Wired connection 1'.
ping: connect: Network is unreachable	Missing gateway, or the assigned IP is on a different VLAN/Subnet than the gateway.	Verify your router's subnet. If router is 10.0.0.1, your Pi IP must be 10.0.0.x/24, not 192.168.1.x.
Warning: ipv4.addresses: invalid prefix length	Typing the subnet mask (255.255.255.0) instead of CIDR notation.	Change 192.168.1.50/255.255.255.0 to 192.168.1.50/24.

FAQ: Making Your Pi's IP Static

How do I make Raspberry Pi IP static without editing config files?

Using nmcli is the definition of avoiding config file edits. When you run nmcli con mod, NetworkManager compiles your inputs into a binary keyfile located in /etc/NetworkManager/system-connections/. You never need to touch a text editor like nano or vim, which eliminates syntax errors like missing brackets or incorrect indentation that plague manual dhcpcd.conf edits.

Why did my /etc/dhcpcd.conf static IP stop working in 2024?

Raspberry Pi OS 'Bookworm' (released late 2023) completely deprecated dhcpcd in favor of NetworkManager to align with upstream Debian standards and improve modern Wi-Fi security (WPA3). If you flash a new SD card using the Raspberry Pi Imager today, dhcpcd is not installed. Any instructions referencing /etc/dhcpcd.conf are referencing an OS architecture that no longer exists on current downloads.

Can I set a static IP on both eth0 and wlan0 simultaneously?

Yes, but you must configure them as separate connection profiles. Run nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.50/24 for Ethernet, and nmcli con mod "YourWiFiSSID" ipv4.addresses 192.168.1.51/24 for Wi-Fi. Warning: If both interfaces are active on the same subnet, Linux routing tables will experience asymmetric routing issues. It is highly recommended to assign them to different subnets (e.g., VLAN 10 for wired, VLAN 20 for Wi-Fi) or use NetworkManager's ipv4.route-metric to strictly prioritize the Ethernet link.