How to Edit the Hosts File on Mac (/etc/hosts)

Hosts file location on Mac:

/etc/hosts

Editing the hosts file on Mac is a common task for developers, but it can be frustrating with permission issues, commands to memorize, and DNS cache to flush. This guide covers the Terminal method and the modern alternative with a graphical interface.

Next: flush DNS on Mac · hosts file not working on Mac

How to edit the hosts file on Mac

To edit the hosts file on Mac, open it with administrator rights in Terminal and save your changes to /etc/hosts:

1. 1Open Terminal (Cmd + Space, type Terminal, press Enter).
2. 2Run sudo nano /etc/hosts and enter your administrator password.
3. 3Add a new line with the IP address, a space, then the domain, for example 127.0.0.1 mysite.test.
4. 4Save with Ctrl+O then Enter, and exit with Ctrl+X.
5. 5Flush DNS with sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder.

The detailed Terminal and GUI methods are below.

Why edit the hosts file on Mac?

The hosts file allows you to redirect domain names to specific IP addresses, locally on your Mac. Here are the most common use cases:

Local web development

• Create custom domains like myproject.local
• Simulate multi-domain environments
• Test configurations before going to production

Testing and debugging

• Point a production domain to a staging server
• Test a server migration before changing official DNS
• Isolate services for debugging

Site blocking

• Block distracting sites
• Block ads at the system level

Terminal method: sudo nano /etc/hosts

This is the traditional method, used by developers for decades.

Step 1: Open Terminal

Several ways to open Terminal on Mac:

• Spotlight: Press Cmd + Space, type "Terminal", then Enter
• Finder: Applications > Utilities > Terminal
• Launchpad: Search for Terminal in the app grid

Step 2: Open the file with nano

Type the following command and press Enter:

sudo nano /etc/hosts

The system will ask for your administrator password. Type it (nothing appears during input, that's normal) and press Enter.

Step 3: Edit the file

You'll see the current contents of the hosts file. By default, it looks like this:

##
# Host Database
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost

Use the arrow keys to navigate to the end of the file, then add your entries:

# My local projects
127.0.0.1 myproject.local
127.0.0.1 api.myproject.local

Step 4: Save and quit

• Press Ctrl + O to save
• Press Enter to confirm
• Press Ctrl + X to quit nano

Step 5: Flush DNS cache (crucial)

This step is often forgotten. Without it, your changes may not take effect.

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

Sources and further reading

• Terminal User Guide (Apple Support)
• The hosts file explained (Wikipedia)
• hosts(5) manual page (man7.org)

Common problems with Terminal

"Permission denied"

Cause: You forgot sudo before the command.

Solution: Use sudo nano /etc/hosts.

Changes not taking effect

Cause: DNS cache wasn't flushed.

Solution: Always run the DNS flush command.

Syntax error

Cause: Incorrect entry format.

Solution: Follow the format IP[TAB or SPACES]domain.

Unreadable file with many entries

Cause: With dozens of entries, finding a specific line becomes tedious.

Solution: Use comments to organize, or switch to a GUI solution.

GUI method: graphical interface

For those who prefer to avoid the terminal or manage many entries, a GUI significantly simplifies the workflow.

Advantages over terminal

• No commands to memorize
• Automatic IP address validation
• Instant search through entries
• Visual organization (drag & drop)
• Enable/disable entries without deleting them
• Automatic backup before each modification
• Built-in one-click DNS flush

How it works with ToggleHosts

1. 1Launch the app - The interface displays all your current hosts entries
2. 2Add an entry - Fill in the IP, domain, and optionally a comment
3. 3Validate - The app checks the syntax and applies the change
4. 4Flush DNS - A button lets you clear the cache instantly

Advanced features

Environment management

Create groups of entries (Dev, Staging, Production) and switch between them with one click.

JSON Import/Export

Share your configurations with your team.

History and backups

Each modification automatically creates a backup.

Prefer a visual walkthrough of the Mac path and safe editing?

Comparison: Terminal vs GUI

Verify that your changes work

After modifying the hosts file and flushing DNS cache:

Test with ping

ping myproject.local

Expected result:

PING myproject.local (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.042 ms

Test in browser

Open http://myproject.local in your browser.

Advanced troubleshooting

The .local domain is slow on Mac

macOS uses Bonjour (mDNS) for .local domains, which can create delays.

Solution: Use .test or .localhost instead of .local.

The browser ignores the hosts file

Some browsers have their own DNS cache.

Solution:

• Chrome: chrome://net-internals/#dns then "Clear host cache"
• Firefox: about:networking#dns then "Clear DNS Cache"

Best practices for daily use

If you edit /etc/hosts regularly, treat it like project configuration rather than a random system file.

• Add comments before each group.
• Use .test domains for local development.
• Keep production-domain overrides temporary.
• Add both 127.0.0.1 and ::1 when needed.
• Back up before bulk imports.
• Flush DNS after every change.
• Clear Chrome DNS cache when Chrome ignores the update.

Example:

# Client: Acme
127.0.0.1 app.acme.test
127.0.0.1 api.acme.test
::1 app.acme.test
::1 api.acme.test

# Temporary migration - remove after launch
203.0.113.50 www.example.com

Team workflow

For teams, avoid sending raw snippets in chat. Instead:

• Keep a documented list of required local domains.
• Export/import hosts profiles with ToggleHosts.
• Use the same naming convention across the team.
• Include hosts setup in onboarding docs.
• Add a rollback note for temporary migration entries.

This prevents the classic bug where one developer tests api.local, another tests api.test, and nobody is hitting the same service.

Conclusion

Editing the hosts file on Mac is an essential skill for any developer. The Terminal method remains viable for one-off changes, but for daily management, a graphical interface like ToggleHosts saves precious time and avoids errors.

Also on other platforms: see our main edit host file guide for Windows and Linux, or the dedicated Windows and Linux tutorials.

Whatever method you choose, never forget: use sudo, check the syntax, and flush DNS cache.

To deepen your knowledge, check our complete guide to the hosts file or learn how to block ads with the hosts file.