How to Change Hostname on Debian 12 (Step-by-Step)

Change hostname on Debian 12 with hostnamectl, a Debian-compatible /etc/hosts entry, and a final resolver check. You can complete the change in about five minutes without rebooting, then reconnect over SSH to refresh your prompt.

Prerequisites

• Debian GNU/Linux 12 (Bookworm) on the VPS.
• An SSH connection as root, or a normal user with working sudo privileges.
• A new short hostname such as web01, or an FQDN such as web01.example.com; use lowercase letters, numbers, hyphens, and dots for the static name.
• Access to your DNS provider if the FQDN must resolve from other computers. Local resolution can be configured on the VPS without a public domain.
• A VPSLake Linux VPS if you need a Debian server for this procedure.

Step 1: Check the current hostname

Capture the current values first so you can tell a persistent hostname from a name supplied by the network or returned by local DNS.

cat /etc/os-release
hostnamectl status --static
hostnamectl status --pretty
hostnamectl status --transient
hostname
hostname --fqdn

The release file should identify Debian 12 (Bookworm). A blank pretty hostname is normal, and the transient value may be blank when no network-provided hostname exists.

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
old-web.example.com

old-web.example.com
old-web.example.com

The static hostname is the value you will make permanent. The pretty hostname is optional and can contain spaces; it is a description for people, not the name that DNS or most services use.

Step 2: Set the persistent hostname

Use hostnamectl so Debian updates the running system and /etc/hostname together instead of leaving those two sources out of sync.

sudo hostnamectl set-hostname NEW_HOSTNAME
hostnamectl status --static
cat /etc/hostname

Replace NEW_HOSTNAME with web01 or web01.example.com. Do not include spaces, underscores, or a final dot. Debian 12’s hostnamectl accepts a DNS-style static name up to 64 characters; the Bookworm hostnamectl manual also distinguishes static, transient, and pretty hostnames.

The command normally prints no status message. Both checks should now show the same name:

web01.example.com
web01.example.com

If you want a human-readable label as well, set the pretty hostname independently:

sudo hostnamectl set-hostname "Production web server" --pretty
hostnamectl status --pretty

That optional label may contain spaces, but it does not create a DNS record or replace the static hostname.

Step 3: Update Debian’s local hosts entry

The hostname can be correct while hostname --fqdn still returns an old value, so update the local mapping that Debian commonly keeps on 127.0.1.1.

Open the file:

sudo nano /etc/hosts

Keep the existing localhost and IPv6 records. Replace the old machine-name line, or add one 127.0.1.1 line in this form:

127.0.0.1 localhost
127.0.1.1 NEW_HOSTNAME NEW_SHORT_NAME

Replace NEW_HOSTNAME with the full value, such as web01.example.com, and NEW_SHORT_NAME with web01. If you chose only a short hostname, use 127.0.1.1 web01 instead. Keep one machine-name entry rather than leaving an old and new 127.0.1.1 line together.

Save the file, then check both forms:

hostname --fqdn
hostname -s
getent hosts NEW_HOSTNAME

For the example above, successful output resembles:

web01.example.com
web01
127.0.1.1  web01.example.com web01

This mapping is local to the VPS. If other systems must resolve the name, create an A record for IPv4 or an AAAA record for IPv6 with your DNS provider. Public DNS and reverse DNS are separate from this operating-system change.

Step 4: Stop cloud-init from undoing the change

Only some VPS images use cloud-init; check before editing its configuration, because installing it just to rename Debian is unnecessary.

if command -v cloud-init >/dev/null 2>&1; then
  cloud-init status --long
else
  echo "cloud-init is not installed"
fi

If the hostname remains correct after reboot, leave cloud-init alone. If cloud-init is installed and restores the old value during boot, add a small drop-in that tells its hostname module to preserve the local setting:

sudo install -d -m 0755 /etc/cloud/cloud.cfg.d
printf '%s\n' 'preserve_hostname: true' | sudo tee /etc/cloud/cloud.cfg.d/99-preserve-hostname.cfg
sudo hostnamectl set-hostname NEW_HOSTNAME

Replace NEW_HOSTNAME with the same value used in Step 2. The tee command should echo the saved setting:

preserve_hostname: true

The cloud-init module reference documents preserve_hostname. If the VPS provider applies a hostname from instance metadata, update that provisioning value too; otherwise it can compete with the local file on later boots.

Step 5: Refresh SSH and dependent services

The kernel uses the new hostname immediately, but an existing shell prompt or application that reads the name only at startup may keep displaying the old value.

Confirm the active name and its persistent file:

hostname
hostnamectl status --static
cat /etc/hostname

All three lines should contain the new hostname:

web01.example.com
web01.example.com
web01.example.com

Open a second SSH session to get a freshly built prompt before closing the first one. Restart only an application that is known to cache the hostname, using its real systemd unit:

sudo systemctl restart YOUR_SERVICE

Replace YOUR_SERVICE with an actual service name. Changing the hostname alone does not require restarting networking or rebooting the VPS.

Verify the new hostname

Run this final set after editing /etc/hosts. It checks the persistent value, the short form, the fully qualified result, and the address returned by Debian’s resolver.

hostnamectl status --static
hostname -s
hostname --fqdn
getent hosts NEW_HOSTNAME

For an FQDN such as web01.example.com, the first three results should be the new name, its short form, and the new FQDN. The final line should return the 127.0.1.1 mapping or the expected DNS address. If these values agree, Debian 12 is using the new hostname locally.

Troubleshooting

hostnamectl: invalid hostname

The static value contains a character Debian rejects, usually a space, underscore, or trailing dot. Use lowercase letters, numbers, hyphens, and dots for NEW_HOSTNAME; put spaces only in the separate --pretty value. Check that each DNS label starts and ends with a letter or number.

hostname --fqdn still returns the old name

The static hostname changed, but /etc/hosts still maps 127.0.1.1 to the previous name or contains duplicate machine-name lines. Inspect the relevant entries and keep one mapping for the new value:

grep -nE '127\.0\.1\.1|OLD_HOSTNAME|NEW_HOSTNAME' /etc/hosts
getent hosts NEW_HOSTNAME

Replace both uppercase placeholders with real values before reading the result. If the local file is correct but a different computer sees the old name, update public DNS and wait for its cached record to expire.

The hostname changes back after a reboot

Cloud-init or provider metadata is applying a name during boot. Check cloud-init status --long, add the 99-preserve-hostname.cfg drop-in from Step 4 when cloud-init is responsible, and update the VPS provisioning hostname if the provider continues to overwrite it.

Failed to set hostname: Access denied

The account lacks the privilege required to change the system name. Run the command with sudo, verify that sudo -v succeeds, or reconnect as root; do not try to work around the error by changing file permissions.

Next steps

• Create the public A/AAAA record and test it from a separate network if the FQDN is used by websites, mail, TLS, or monitoring.
• Request a matching PTR record through the system that manages your VPS IP when reverse DNS matters.
• Update monitoring, backup, configuration-management, and SSH inventory entries that still use the previous hostname.

FAQ

Do I need to reboot Debian 12 after changing the hostname?

No. hostnamectl changes the active name and writes the persistent hostname file immediately. Reconnect to refresh the SSH prompt, and restart only applications that cache the name at startup.

Can I use a short hostname without a domain?

Yes. A name such as web01 works for a standalone VPS or a private network. Choose an FQDN when mail, TLS, monitoring, or multi-server tools require a globally unique name, and make sure it resolves through /etc/hosts or DNS.

Does changing the hostname update DNS or reverse DNS?

No. The command changes Debian’s local system identity only. Public forward DNS, reverse DNS, and any label shown in a VPS client area are managed separately.

Why does Debian use 127.0.1.1 for the machine name?

Debian commonly keeps 127.0.0.1 for localhost and reserves 127.0.1.1 for the local machine name. That lets local programs resolve the VPS name without depending on public DNS or a possibly changing network address.