Migrate to RunxBuild and earn up to $50 in hosting credit on your first deposit.

Calculate your savings
unxBuild
Log in Get Started
Back to Blog Tutorial

Change a Linux Hostname the Right Way (and the Wrong Way to Spot)

Sean

Platform Writer

Jun 30, 2026
4 min read

Change a Linux hostname the right way with hostnamectl set-hostname, or the wrong way by editing /etc/hostname without /etc/hosts. The wrong way leaves hostname -f returning the old value and sudo logging warnings.

Change a Linux Hostname the Right Way (and the Wrong Way to Spot)

Table of contents

The right way: hostnamectl

One command, on any systemd-based Linux distribution:

sudo hostnamectl set-hostname new-hostname.example.com

This sets all three hostname types (static, pretty, transient) and updates /etc/hostname and /etc/machine-info. The change is immediate and survives a reboot.

Verify with hostnamectl (no arguments) or cat /etc/hostname.

The /etc/hosts edit

The hostnamectl command does not edit /etc/hosts. The team that skips this step gets hostname -f returning the old value.

Edit /etc/hosts:

127.0.0.1   localhost
127.0.1.1   new-hostname.example.com new-hostname

The 127.0.1.1 line is what hostname -f resolves. Without it, the team gets a “hostname: Name or service not known” error from tools that resolve the FQDN.

The wrong way: only editing /etc/hostname

The classic mistake:

sudo nano /etc/hostname
# change old-hostname to new-hostname
sudo reboot

The hostname changes, but hostname -f still returns the old name. sudo logs:

sudo: unable to resolve host new-hostname: Name or service not known

Every sudo invocation logs this warning. The fix: also edit /etc/hosts.

The legacy approach

For non-systemd systems:

  1. Edit /etc/hostname.
  2. Edit /etc/hosts.
  3. Reboot.

Or use hostname new-hostname for a temporary change that doesn’t survive reboot. The team that uses hostname for a permanent change has to remember to also edit the files.

Verifying the change

The right tests:

  • hostname: returns the short hostname (web-prod-01).
  • hostname -f: returns the FQDN (web-prod-01.example.com).
  • hostname -d: returns the domain (example.com).
  • hostnamectl: shows all three hostname types.
  • cat /etc/hostname: shows the static hostname.

The team that sees hostname returning the new name but hostname -f returning the old has the /etc/hosts issue.

What usually goes wrong

The four pitfalls:

  • Forgot /etc/hosts. The team that runs hostnamectl set-hostname but does not edit /etc/hosts gets hostname returning the new value and hostname -f returning the old.
  • Forgot to reload daemons. Postfix keeps using the old hostname until reloaded.
  • Picked an invalid hostname. Underscores or leading hyphens are rejected by some tools.
  • Hostname conflicts with another host. Two hosts with the same name on the same network cause inconsistent behavior.

The container hostname patterns

Containers handle hostnames differently:

  • Docker. The container’s hostname is the container ID by default. Set with docker run --hostname myhost. The container’s /etc/hostname and /etc/hosts are set automatically.
  • Docker Compose. Set hostname: myhost in the service definition. Alternatively, set container_name: mycontainer (but this affects networking too).
  • Kubernetes. The pod’s hostname is the pod name by default. Set with spec.hostname in the pod spec. Set subdomain with spec.subdomain.
  • systemd-nspawn. Set with --hostname=myhost at boot.

The team that runs production services in containers sets the hostname explicitly to match the service name. The auto-generated hostname (container ID, pod name) is useless for logs and monitoring.

The cloud-init angle

On cloud instances (AWS EC2, GCP Compute Engine, Azure VMs), cloud-init can set the hostname at first boot:

#cloud-config
hostname: web-prod-01
fqdn: web-prod-01.example.com
manage_etc_hosts: true

Cloud-init also updates /etc/hosts automatically. The team that uses cloud-init for hostname management has the hostname set correctly on first boot, no post-boot script needed.

For Kubernetes deployments, the equivalent is the pod’s hostname field. For Docker, the equivalent is the --hostname flag or compose hostname: field.

FAQ

Does the hostname change require a reboot?

No, with hostnamectl. Yes, with the legacy approach.

Why does hostname -f return the old value?

Because /etc/hosts was not updated. The team that edits both /etc/hostname and /etc/hosts has the right behavior.

Can I use a domain name as the hostname?

Yes. The team that uses web-prod-01.example.com as the hostname has a fully-qualified hostname.

What’s the difference between static and pretty hostname?

Static is the kernel-level hostname. Pretty is the human-readable form. Transient is set by DHCP. hostnamectl set-hostname sets all three.

What’s the difference between hostname and domain name?

Hostname is the name of a single host. Domain name is the name of a network or zone. The fully qualified domain name (FQDN) combines both: host.example.com is host host in domain example.com.

Can I have multiple hostnames on one machine?

Yes, via CNAME or A records in DNS, or via hostname aliases in /etc/hosts. The kernel-level hostname is one; DNS can have many. The team that runs multiple services on one host uses multiple DNS names pointing to the same IP.

Does the hostname affect SSH?

Yes, in the host key fingerprint. The team that connects to a host by a different hostname than what’s in the host key gets a warning. The fix: connect by the canonical hostname, or update known_hosts.

If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.

Useful related references:

#hostname#linux#hostnamectl#troubleshooting#systemd