Skip to content

Static IP Configuration on Raspberry Pi OS

For most home networks, use a DHCP reservation on the router. The Pi keeps using DHCP, while the router assigns a stable address. Use a device-side static IP when your network requires it, with an agreed address plan and a way to recover access.

Choose DHCP reservation or a static IP

Your situation Start here
You administer the home router and want a stable address Reserve a DHCP address
A network administrator has assigned a manual IPv4 configuration Plan it, then use a separate Pi profile
You only want an easier SSH name Try the existing hostname or router DNS first
The Pi is already unreachable Diagnose the connection before changing addresses

A fixed address does not enable SSH, open a firewall or make a service reachable from the internet. Do not add port forwarding for this LAN exercise.

Before you start

This procedure covers IPv4 on Raspberry Pi OS Bookworm or Trixie with NetworkManager, for an ordinary Ethernet or Wi-Fi connection to one home LAN. Keep IPv6 unchanged. VPNs, bridges, VLANs and workplace networks need their own routing policy.

Commands run on the Pi unless labelled client computer. You need a working connection, permission to administer the network, and a local console or separately verified recovery link before activation. Keeping an SSH window open does not protect it from an address change.

Outcome: reach the intended address, check the active profile, route and name resolution, then open a fresh SSH login. If necessary, return to the original profile.

Start with read-only checks:

1
2
3
4
5
6
cat /etc/os-release
nmcli --version
nmcli device status
nmcli -f NAME,UUID,TYPE,DEVICE connection show --active
ip -brief address
ip route

If nmcli is missing or the service is inactive, use NetworkManager diagnosis. Do not replace networking services just to follow this article.

1. Prefer a router DHCP reservation

  1. In the router interface you administer, find the Pi's current DHCP lease and the connected interface's MAC address. Ethernet and Wi-Fi have different identities.
  2. Use its address-reservation/static-lease feature. Follow that router's rules for allowed addresses, existing leases and conflicts; there is no universal DHCP range.
  3. Leave the Pi on automatic addressing. Save the reservation and follow the router's documented lease-renewal procedure during a recovery-access window. The current lease may not change immediately.
  4. Verify the new lease, Pi address and a fresh login. If it fails, restore the previous reservation and use the router's lease list or Pi console to recover.

Inspect the actual device identity, replacing eth0 with the connected interface:

nmcli -f GENERAL.DEVICE,GENERAL.HWADDR,GENERAL.CONNECTION device show eth0

Match this to the router's lease. A reservation can stop matching if the profile's MAC/client identity changes; it is not guaranteed to survive every OS reinstall or policy change. Consult your router's manual for its matching rules.

This is the Raspberry Pi documentation's recommended approach. Stop here if it solves your problem. Do not also configure a manual address on the Pi.

2. Plan the static IP

Obtain the subnet, DHCP pool, exclusions, reservations and manual assignments from the router or network administrator. A failed ping does not prove an address is free: another device may be asleep, disconnected or filtering ICMP.

This is one illustrative network, not a claim about your router:

Setting Example plan
LAN subnet 192.168.10.0/24
DHCP allocation pool 192.168.10.100 through 192.168.10.200
Pi manual address 192.168.10.50/24, separately confirmed unassigned
Gateway 192.168.10.1
DNS resolver 192.168.10.1, only if this router supplies working DNS

Here .50 is outside the example pool, but could still collide with another manual assignment. Do not use the network address .0, broadcast address .255, gateway, or someone else's reservation in this /24 example. Other prefix lengths have different boundaries.

Inspect current DHCP-supplied details using your actual interface:

nmcli -f GENERAL,IP4,IP6 device show eth0

Current values explain the working setup; they do not authorise you to keep a leased address manually. Use the DNS resolver required by your LAN rather than replacing local or split DNS with arbitrary public servers.

3. Create a separate trial profile

Record the working profile UUID, interface and original autoconnect setting somewhere available at the console. A profile name is not an interface name. For Wi-Fi, select the existing working Wi-Fi profile; do not create a new SSID or enter a password here.

Replace the UUID placeholder below and choose a new, unused trial name. If that name already exists, stop and choose another:

1
2
3
4
ORIGINAL_UUID='REPLACE-WITH-THE-WORKING-PROFILE-UUID'
TRIAL_NAME='Pi static trial'
nmcli -f NAME,UUID,TYPE,DEVICE connection show
nmcli -f connection.id,connection.uuid,connection.autoconnect,ipv4,ipv6 connection show uuid "$ORIGINAL_UUID"

If the profile is not the intended one, or its IPv4 method is not the expected auto, investigate before proceeding. Keep output containing network identifiers private.

The next commands create and edit saved configuration. Run one at a time and stop on an error. Clone while the original connection is healthy, then immediately prevent the copy from autoconnecting:

1
2
3
4
sudo nmcli connection clone uuid "$ORIGINAL_UUID" "$TRIAL_NAME"
sudo nmcli connection modify "$TRIAL_NAME" connection.autoconnect no
TRIAL_UUID=$(nmcli -g connection.uuid connection show "$TRIAL_NAME")
nmcli -f connection.id,connection.uuid,connection.autoconnect connection show uuid "$TRIAL_UUID"

Check: the copy has a different UUID, the intended name and autoconnect no. Record its UUID too. Cloning preserves other settings, including Wi-Fi security and IPv6; treat the copy as sensitive configuration. Review unusual manual routes or DNS policy before proceeding. None of these commands intentionally activates the trial.

Using your approved values instead of this example, change only the clone:

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

Inspect it before activation:

nmcli -f connection.id,connection.uuid,connection.autoconnect,ipv4,ipv6 connection show uuid "$TRIAL_UUID"

Expect ipv4.method to be manual and your chosen address, gateway and DNS to appear. IPv6 retains the original policy. Saved settings do not prove that the device is using them.

4. Activate with recovery access ready

Use the Pi console or a verified alternate connection, not the only SSH path you are changing. Activating the clone on the same interface replaces the original active profile and can immediately drop SSH:

sudo nmcli connection up uuid "$TRIAL_UUID"

An error or lost session is not a reason to restart NetworkManager or disable another service. Use rollback if the intended connection fails.

5. Verify the actual connection

On the Pi, substitute the correct interface for eth0:

1
2
3
4
5
nmcli -f NAME,UUID,TYPE,DEVICE connection show --active
nmcli -f GENERAL,IP4,IP6 device show eth0
ip -brief address
ip route
getent ahosts raspberrypi.com

Check each result:

  • The trial UUID is active on the intended device.
  • The intended IPv4 address and prefix are present. Another working interface can hide a failed trial.
  • The expected gateway/default route exists if the LAN needs off-subnet access. With several interfaces or a VPN, use selected-route diagnosis rather than deleting extra routes.
  • The required hostname resolves. getent tests system name resolution, not HTTPS or every DNS server. Repeat with your service hostname.

On a client computer on the intended LAN, open a second terminal and use your own username and approved address:

ssh your-user@192.168.10.50

Test the service you need, not just ping. A host-key warning may mean the address belongs to another machine; verify identity through the trusted console rather than disabling host-key checking.

Make it persistent after verification

The trial is currently manual-only. For an ordinary single-profile-per-interface setup, deliberately select it for automatic activation:

sudo nmcli connection modify uuid "$TRIAL_UUID" connection.autoconnect yes
sudo nmcli connection modify uuid "$ORIGINAL_UUID" connection.autoconnect no

These saved-setting changes do not themselves switch the active profile. Record that the original's autoconnect setting has now changed. Keep other fallback profiles deliberate; do not disable every profile globally. With recovery access ready, schedule a reboot test and repeat the active UUID, address, route, lookup and fresh-login checks. Manual activation alone does not prove persistence.

6. Return to the original profile

At the console or alternate connection, restore ORIGINAL_UUID and TRIAL_UUID from your written record if using a new shell. Do not guess them from an interface name.

Prevent the trial from autoconnecting, then reactivate the original:

sudo nmcli connection modify uuid "$TRIAL_UUID" connection.autoconnect no
sudo nmcli connection up uuid "$ORIGINAL_UUID"

If you changed the original's autoconnect setting, restore its recorded original value. For an original value of yes:

sudo nmcli connection modify uuid "$ORIGINAL_UUID" connection.autoconnect yes

Check the connection and a new login. Use the router lease list to find the restored DHCP address; it need not match the old address. The original's IPv4 settings were not edited, so returning to it restores its addressing policy.

After confirming the original works, you may remove only the trial created here, after checking its UUID:

nmcli -f connection.id,connection.uuid connection show uuid "$TRIAL_UUID"
sudo nmcli connection delete uuid "$TRIAL_UUID"

Deletion removes that saved trial profile. Do not delete the original or all connections. Alternatively, keep the trial with autoconnect off.

Troubleshooting by symptom

  • Trial activation fails: inspect the exact error and device state/reason. Roll back before changing authentication or services.
  • New IP is present, but the client cannot connect: check its LAN/subnet, AP client isolation, duplicate assignments and service listener. The old DHCP address is no longer the intended target.
  • Local access works, but remote destinations fail: check the planned prefix, gateway and selected route. A failed ICMP reply alone does not establish a broken gateway.
  • IP destinations work, but names do not: inspect DNS separately. Preserve required local DNS.
  • A different address returns after reboot: compare active UUIDs and autoconnect choices first. Do not assume managers are conflicting or stop dhcpcd without identifying who manages the device.

Frequently asked questions

Should I edit /etc/dhcpcd.conf on Bookworm or Trixie?

Not for a NetworkManager-managed connection. Use the active manager. Older or customised installations need version-specific instructions; do not mix a legacy service restart with this procedure.

Can I use nmtui instead?

Yes, if installed. Edit the separate trial profile using the same address plan, keep autoconnect off until ready, and retain the original. The interface does not replace activation checks and rollback.

Should I disable IPv6 to make IPv4 stable?

No. IPv6 addressing and routing are separate. Disabling them is not a general repair for an IPv4 mistake.

Next steps and references

Checkpoint: why does an unanswered ping not prove an address is unused? How does a saved manual profile differ from an active profile?

Continue with connection diagnosis if a check fails, or choose remote access once the LAN works. A stable address is not a substitute for authentication.

References reviewed on 4 November 2026: Raspberry Pi networking, nmcli profile commands, and profile properties.

Donate