Ubuntu Hosts File: Location and Editing

When you want a hostname to resolve to a chosen address on Ubuntu, you can add a local mapping. The hosts file is a plain-text file that associates IP addresses with hostnames for local name resolution.

This article walks through editing /etc/hosts to add a hostname mapping. It also shows how to check the lookup result.

TL;DR

Ubuntu reads local hostname mappings from /etc/hosts through its name-service configuration, so an entry can direct one machine to an IP address without changing public DNS.

• Find the file at /etc/hosts.
• Each mapping starts with an IP address, followed by a canonical hostname and optional aliases.
• Use a privileged editor to change it, then verify name resolution and network reachability as separate checks.

What Is the Ubuntu Hosts File?

The Ubuntu hosts file is a plain-text table at /etc/hosts that associates IP addresses with hostnames. It gives the local machine a name-to-address mapping that can be consulted during name resolution.

A line has an address first, then a canonical hostname and optional aliases, separated by spaces or tabs. A hash mark starts a comment that continues to the end of that line.

192.0.2.25   staging.example.test   staging # temporary test target

The documentation-only IPv4 address 192.0.2.25 is used in this example. The two names on the line resolve to that same address when the local lookup path consults this file.

DNS normally supplies address records for names across networks. The hosts file is a local override, not a replacement for a DNS server. Whether an application consults it first depends on the system’s Name Service Switch configuration and on the application’s own resolver behavior.

How to Edit the Ubuntu Hosts File Step by Step

Use a terminal editor with elevated permission because ordinary users cannot write this system file. Keep the existing loopback and machine-name entries, then add a commented line for the test mapping.

Step 1: Open the file for editing

Open the file in Nano with administrative permission by running this command on your Ubuntu machine:

sudo nano /etc/hosts

This command requires authorization and changes no file until you save an edit. I did not run it here because it would require elevated access to a system file. In Nano, move to a new line at the end and enter the test server’s IP address and name.

Step 2: Add one mapping and save it

Use an address assigned to the intended test server. Keep the alias on the same line when both names should reach the same machine. A fully qualified name includes its domain suffix, such as staging.example.test, while a short alias can be convenient on a private network.

192.0.2.25 staging.example.test staging

Save in Nano with Ctrl+O, confirm the filename, then exit with Ctrl+X. Replace the documentation address and example names with values for your own environment before saving. If the editor reports that it cannot write the file, exit without saving and reopen it with the privileged command in Step 1.

Step 3: Check the resolved address

Use getent to query the system name-service path. It follows the configured NSS lookup sequence, which makes it a useful way to inspect the answer an application may receive.

getent hosts localhost

The command returned this line in the captured run:

::1             localhost

The output shows ::1, the IPv6 loopback address. For your own hostname, compare the address at the start of the line with the entry you added. A different answer can point to a spelling error, another matching entry, or a different lookup source in the hosts: line of /etc/nsswitch.conf.

Step 4: Separate name lookup from connection

A successful name lookup only gives the address to use. It does not show that a server is online or that its application accepts connections. A ping test checks a different thing because it sends ICMP echo requests, which some hosts do not answer.

For a web service, check it with the client or health endpoint used by that service. The LinuxForDevices ping guide explains reachability. A ping timeout alone does not disprove a valid hosts mapping.

Common Problems With an Ubuntu Hosts Entry

Errors usually trace back to an invalid line, a competing mapping, or an application that has kept an older answer. Check those causes before changing system-wide DNS settings.

IPv6 entries use an IPv6 address in the first field and the same hostname fields after it. The standard loopback name is commonly mapped to 127.0.0.1 for IPv4 and ::1 for IPv6. Leave the distribution’s existing defaults intact because local software may rely on both address families.

A hosts file does not support wildcard names, so add each hostname as its own explicit name. The override applies only to the machine whose file you edit. It does not update a router, DNS server, or other clients on the network.

Some distributions or network-management tools generate entries in this file. Comments near a generated line can identify its source. Avoid deleting those lines without checking the tool that owns them, or it may recreate them later.

To undo a test, reopen /etc/hosts and remove the added line or comment it with #. Then query the affected name again through getent hosts. The answer may come from another configured source or return no result if no other source knows the name.

Changes usually take effect without a reboot, although an application can retain a cached answer. If getent shows the new value but the application still uses the old one, restart or refresh that application.

Conclusion: Keep Local Overrides Small

Keep each local override specific and document its purpose with a short comment. getent checks the configured name lookup path. The application’s connection check answers whether the service can be reached.

For related tasks, see how to change DNS on Linux, the Netcat guide for checking a service port, and Wi-Fi troubleshooting on Linux Mint for network connectivity checks. Those guides cover behavior beyond this local mapping.

FAQ

The answers below cover the file location and how far a local mapping reaches.