Short answer: on Windows, open Notepad as administrator, open C:\Windows\System32\drivers\etc\hosts, add a line with an IP address and a name such as 203.0.113.10 example.com, and save. On macOS and Linux, run sudo nano /etc/hosts and add the same line. Then flush the DNS cache so the new entry is used straight away.
| System | File | Edit with | Then flush |
|---|---|---|---|
| Windows 10, 11, Server | C:\Windows\System32\drivers\etc\hosts | Notepad, run as administrator | ipconfig /flushdns |
| macOS | /etc/hosts | sudo nano /etc/hosts | sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder |
| Linux | /etc/hosts | sudoedit /etc/hosts | Only if a cache runs (systemd-resolved, nscd) |
The hosts file is the oldest name lookup there is: a plain text table that your own computer checks before it asks DNS. Whatever you put there wins on that one machine and nowhere else, which makes it the standard way to preview a site on a new server, block a domain, or give a local project a name. The syntax below follows the hosts(5) and nsswitch.conf(5) man pages and the comment block in Windows’ own hosts file; the getent output comes from a Debian 12 server with glibc 2.36.
Hosts file syntax: one address, then its names
# lines starting with # are comments
127.0.0.1 localhost
::1 localhost
203.0.113.10 example.com www.example.com # new server, remove after the move
0.0.0.0 ads.example.net
127.0.0.1 myshop.test- Address first, then one or more names, separated by spaces or tabs. The first name is the canonical one, the rest are aliases.
- IPv4 and IPv6 both work. A name may have one line for each.
- Everything after
#is a comment, on its own line or at the end of an entry. - Exact names only. No wildcards (
*.example.comdoes not work), soexample.comandwww.example.comare separate names. - No ports, paths or
http://. The file maps names to addresses, nothing more. It cannot sendexample.comto port 8080 or to another URL. - Addresses only. Mail and other record types still come from DNS; systemd-resolved’s man page says so explicitly for MX lookups.
How do I edit the hosts file on Windows?
- 1Start Notepad as administrator
Press the Windows key, type
Notepad, right-click it and choose Run as administrator. Without that, Windows lets you open the file but refuses to save it. - 2Open the file
File → Open, paste
C:\Windows\System32\drivers\etcinto the address bar, and switch the file-type filter from Text Documents (*.txt) to All Files. The file is calledhosts, with no extension. - 3Add your line and save
Add the entry at the end, for example
203.0.113.10 example.com www.example.com, and press Ctrl+S. Keep the encoding Notepad offers (UTF-8 or ANSI).
The same from an administrator PowerShell, without touching the mouse:
notepad "$env:windir\System32\drivers\etc\hosts"
# or append one line directly; the leading line break protects a last line without one
Add-Content -Path "$env:windir\System32\drivers\etc\hosts" -Value "`r`n203.0.113.10 example.com www.example.com"The usual problems on Windows are all about saving: an “access denied” or “you don’t have permission” message when you save means Notepad is not running as administrator; a new file called hosts.txt next to the real one means the *.txt filter was still on; and if the file is marked read-only (some ad blockers and security tools do that), clear Read-only under its Properties first. Windows hides known extensions by default, so check with dir $env:windir\System32\drivers\etc in PowerShell.
How do I edit /etc/hosts on macOS and Linux?
sudo nano /etc/hosts # add the line, Ctrl+O and Enter to save, Ctrl+X to quit
# or, on Linux, with your own editor and a safe temporary copy:
sudoedit /etc/hostsOn macOS /etc is a link to /private/etc, so both paths are the same file. On a Linux server, look at the first lines before you edit: if they say the file is managed by cloud-init (manage_etc_hosts), it is rewritten at boot and your change has to go into the template the comment names. The line with the machine’s own hostname matters too; deleting it makes sudo complain, as described in temporary failure in name resolution.
Flush the DNS cache afterwards
The hosts(5) man page says changes normally take effect immediately, except where a program caches them. In practice that means three caches:
- The system cache:
ipconfig /flushdnson Windows, the two macOS commands from the table above, and on Linux only where a caching service runs. systemd-resolved reads/etc/hostsitself, before it asks any DNS server; if an old answer lingers,sudo resolvectl flush-cachesclears its cache. All variants are in how to flush the DNS cache. - The browser’s own cache: in Chrome open
chrome://net-internals/#dns(in Edge,edge://net-internals/#dns) and click Clear host cache; in Firefox,about:networking#dnsand Clear DNS Cache. - Open connections: a browser that already has a keep-alive connection to the old address keeps using it. In Chrome,
chrome://net-internals/#sockets→ Flush socket pools, or simply restart the browser.
How do I check that the entry works?
Use a tool that resolves names the way applications do. nslookup and dig do not: they send a query straight to a DNS server and never read the hosts file, so they keep showing the old address even when your entry works.
ping -n 1 example.com # "Pinging example.com [203.0.113.10]" = hosts entry used
Resolve-DnsName example.com # reads the hosts file; add -NoHostsFile to skip itgetent hosts example.com # goes through nsswitch.conf, like every program
getent hosts localhost
# ::1 localhost ip6-localhost ip6-loopbackThe last output is real, from a Debian 12 server. For a website, curl -sv -o /dev/null https://example.com/ prints a line like Trying 203.0.113.10:443, the address it actually connected to.
What is the hosts file good for?
Testing a site on a new server before you change DNS
Point the domain at the new server on your own computer only, click through the whole site there, and leave DNS alone until everything works. Everybody else still reaches the old server meanwhile. Add a line for www too, and, if the domain has an AAAA record, an IPv6 line for the new server: some systems (macOS is the usual example) still take the IPv6 address from DNS when only an IPv4 line exists.
HTTPS is the catch. A Let’s Encrypt certificate requested with the HTTP check cannot be issued yet, because Let’s Encrypt resolves the domain through public DNS and lands on the old server. Copy the current certificate across for the test, use the DNS check, or accept the browser warning for a test that does not involve logins. For a quick look without editing any file, curl --resolve example.com:443:203.0.113.10 https://example.com/ does the same for one request. The full move is in the server migration checklist, and the DNS side afterwards in pointing a domain to a VPS. Remove the line when you are done, or you will be testing the wrong server six months later.
Blocking a domain
0.0.0.0 tracker.example.net
0.0.0.0 www.tracker.example.net0.0.0.0 is the usual target in blocklists because it is no real destination, while 127.0.0.1 sends the request to whatever web server runs on your own machine. (Linux treats a connection to 0.0.0.0 as local too, so there the two behave alike.) Every subdomain needs its own line, since wildcards do not exist here. For a whole household or office, a filtering DNS resolver is easier to keep up to date than one hosts file per device.
Local development names
Mapping myshop.test to 127.0.0.1 lets you run a project under a real hostname, which matters for cookies, virtual hosts and CORS. Use the .test top-level domain, reserved for exactly this in RFC 2606, and not .dev: that is a real top-level domain whose sites browsers only open over HTTPS. Names under .localhost need no entry at all in Chrome and Firefox, which resolve them to the loopback address on their own, as RFC 6761 recommends.
Why is my hosts file being ignored?
| Cause | How to tell | Fix |
|---|---|---|
| Saved as hosts.txt | dir shows hosts.txt next to hosts | Save again with All Files selected, then delete hosts.txt |
| Not saved at all | Permission error on save | Run the editor as administrator, or use sudo |
| Wrong syntax | Name before the address, a URL, a port or a wildcard | One line: address, space, name |
| Checked with nslookup or dig | ping or getent shows the new address | Nothing to fix: those tools skip the hosts file |
| Browser cache or open connection | Terminal shows the new address, browser the old site | Clear host cache, flush socket pools, restart the browser |
| VPN or proxy resolves the name | Works with the VPN or proxy off | Exclude the domain, or test without them |
| IPv6 from DNS (some systems) | The domain has an AAAA record you did not override | Add an IPv6 line for the same name |
| File regenerated | Your line is gone after a reboot | cloud-init template, WSL's generateHosts, or a Docker container's own file |
Secure DNS in the browser is rarely the culprit, although it is often blamed. Firefox lists names from the hosts file among the domains it never sends over DNS over HTTPS, according to its developer documentation, and Chromium’s host resolver serves hosts-file entries before any DNS task, including secure ones (read in its source code on 21.10.2026). An HTTP or SOCKS proxy with remote DNS is different: the browser hands the name to the proxy, and the proxy never sees your hosts file. The same goes for some apps that bring their own resolver.
Linux: the order in /etc/nsswitch.conf
On Linux, the C library decides whether the hosts file comes before DNS, and the hosts: line in /etc/nsswitch.conf sets the order. On the Debian 12 server we read it on, the line is:
hosts: files myhostname dnsfiles is /etc/hosts, myhostname answers for the machine’s own name, and dns comes last, so the hosts file wins. Systems with systemd-resolved often have a resolve entry as well, and resolved reads /etc/hosts itself (unless ReadEtcHosts=no). If someone has moved dns in front of files, as in one of the man page’s examples, DNS answers first and the hosts file becomes a fallback at best. getent hosts NAME always follows this line, which is why it is the right test.
How do I reset the hosts file on Windows?
The default Windows hosts file contains only comments, including the two commented-out localhost lines; Windows resolves localhost itself. To reset it, delete every line that does not start with #, or replace the file with an empty one named hosts. Nothing breaks: the next lookup simply goes to DNS. On Linux, keep the localhost lines and the line with the machine’s own hostname.
The hosts file on a VPS
On a server you rent, the hosts file mostly does housekeeping: the hostname line, and sometimes a name for a database or backend on a private address, so that configs say db1 rather than an IP. For anything other people should reach, publish a DNS record instead; the hosts file only ever answers for the machine it sits on. How names get resolved from there on is in what is DNS, and when a name does not resolve at all, start with DNS_PROBE_FINISHED_NXDOMAIN.
Frequently asked
Where is the hosts file on Windows?
C:\Windows\System32\drivers\etc\hosts, a file named hosts with no extension. Open Notepad as administrator, switch the file filter from Text Documents to All Files and open it from that folder; without administrator rights Windows lets you read it but not save it.
Do I need to restart after editing the hosts file?
No. Changes normally apply at once. Run ipconfig /flushdns on Windows, or sudo dscacheutil -flushcache and sudo killall -HUP mDNSResponder on macOS, to drop answers cached before the edit, and clear the browser's host cache or restart the browser, because an open connection to the old address can keep being used.
Why is my hosts file not working?
The usual causes are a file saved as hosts.txt, an edit that was never saved because the editor lacked administrator rights, a wrong line format (the address comes first, with no port or http://), a browser still using a cached answer or an open connection, a VPN or proxy that resolves names remotely, or, on some systems such as macOS, an AAAA record in DNS that an IPv4-only entry does not override. Test with ping or getent hosts, not nslookup or dig, which skip the hosts file.
Can I use wildcards or ports in the hosts file?
No. Each line maps one address to exact names, so every subdomain needs its own line, and the file cannot send a name to a different port or URL. Wildcards need a local DNS server such as dnsmasq, and a different port needs a reverse proxy.