DEV Community

Locahl
Locahl

Posted on

How to edit /etc/hosts without breaking your local setup

#webdev #devops #tutorial #productivity

Most people open /etc/hosts, change one line, refresh the browser, and hope.

That works until it does not. Then you spend twenty minutes on Permission denied, a forgotten DNS flush, or a commented line from last week that is still active.

This is a simple workflow that keeps hosts edits boring.

What the hosts file does

When your machine resolves a name like myapp.test, it can use a local override before public DNS.

Common cases:

  • Point myapp.test to 127.0.0.1 for local work
  • Point a real domain at a staging IP before DNS cutover
  • Temporarily block a host with 0.0.0.0
  • Give services readable names instead of raw IPs

The idea is simple. The mess comes from how people edit and apply it.

A workflow that holds up

1. Do not treat /etc/hosts as your only copy

Keep a file you own:

~/dev/hosts/personal.hosts
Enter fullscreen mode Exit fullscreen mode

Or one file per project / client. Edit that. Apply it on purpose.

2. Edit the copy, then copy it into place

macOS / Linux:

code ~/dev/hosts/personal.hosts
sudo cp /etc/hosts "/etc/hosts.bak.$(date +%Y%m%d-%H%M%S)"
sudo cp ~/dev/hosts/personal.hosts /etc/hosts
Enter fullscreen mode Exit fullscreen mode

Windows: edit your copy, back up the live file, then replace:

C:\Windows\System32\drivers\etc\hosts
Enter fullscreen mode Exit fullscreen mode

You need admin rights for the live file. That is normal.

3. Flush DNS every time you apply

Make this part of the apply step, not a later panic search.

macOS

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
Enter fullscreen mode Exit fullscreen mode

Windows (Admin)

ipconfig /flushdns
Enter fullscreen mode Exit fullscreen mode

Linux (systemd-resolved)

sudo resolvectl flush-caches
Enter fullscreen mode Exit fullscreen mode

4. Verify in the terminal before the browser 

ping -c 1 myapp.test
# Linux:
getent hosts myapp.test
Enter fullscreen mode Exit fullscreen mode

Right IP in the terminal, wrong page in the browser? Stop rewriting hosts. Look at browser DNS, HTTPS, redirects, or HSTS.

5. Avoid two active lines for the same hostname

This breaks people constantly:

10.0.0.5    www.client.com
127.0.0.1   www.client.com
Enter fullscreen mode Exit fullscreen mode

Pick one. Comment the other, or better, keep separate profile files and swap the whole file.

Example: local frontend + API 

127.0.0.1   shop.test
127.0.0.1   api.shop.test
Enter fullscreen mode Exit fullscreen mode

Frontend env:

NEXT_PUBLIC_API_URL=http://api.shop.test
Enter fullscreen mode Exit fullscreen mode

API env:

APP_URL=http://api.shop.test
Enter fullscreen mode Exit fullscreen mode

Then:

  1. Apply hosts
  2. Flush DNS
  3. Confirm with ping / getent
  4. Open the browser
  5. Only then debug CORS, cookies, or TLS

Hosts bugs and app bugs look the same in a tab. Split them.

Team onboarding

If your README says “paste these 12 lines into hosts,” configs will drift.

Better:

  • Commit a hosts.example
  • Add a short apply script
  • Say which environment the file is for (local, stEgin`, etc.)

Goal: new laptop works in a few minutes, not after three Slack threads.

Short version

  1. Edit a file you own
  2. Back up, then copy into the system hosts path
  3. Flush DNS
  4. Check resolution in the terminal
  5. Keep one active mapping per hostname

That is enough for most local and staging work. If you are changing hosts several times a day across clients, automate the swap with a script or a small hosts manager. The process above still matters either way.

Top comments (0)