Complete Guide to /etc/hosts Syntax and Format

The /etc/hosts file is a fundamental system file that maps domain names to IP addresses. While its concept is simple, mastering its syntax and format is crucial for developers, system administrators, and anyone working with local development environments. This comprehensive guide covers everything you need to know about hosts file syntax, formatting rules, and best practices.

What is the /etc/hosts syntax?

Each active line in /etc/hosts follows the format IP_address hostname [aliases], separated by spaces or tabs. The IP address comes first, then one or more hostnames on the same line. Lines starting with # are comments. Never include http://, paths, or port numbers, only an IP and bare hostnames.

Understanding the hosts file format

The hosts file is a plain text file that follows a strict but simple format. Each line represents a mapping between an IP address and one or more domain names. The file is read line by line, from top to bottom, and the first matching entry takes precedence.

Basic syntax structure

The fundamental format of a hosts file entry is:

IP_address domain_name [optional_aliases...]

Here's what each component means:

• IP_address: The IP address (IPv4 or IPv6) to which the domain should resolve
• domain_name: The primary domain name
• optional_aliases: Additional domain names that should resolve to the same IP, separated by spaces

Essential formatting rules

Understanding these rules will help you avoid common mistakes:

1. One entry per line

Each IP-to-domain mapping must be on its own line. You cannot split entries across multiple lines.

2. Whitespace separation

Use spaces or tabs to separate the IP address from the domain name(s). At least one whitespace character is required, but multiple spaces or tabs are acceptable.

3. Case sensitivity

Domain names in the hosts file are case-insensitive. example.com, Example.COM, and EXAMPLE.com are all treated the same way.

4. No wildcards

The hosts file does not support wildcard patterns like *.example.com. Each subdomain must be explicitly listed.

5. Comments

Lines starting with # are treated as comments and ignored by the system. Use comments to organize and document your entries.

IPv4 address format

IPv4 addresses use the dotted decimal notation: four numbers separated by periods, each ranging from 0 to 255.

Standard IPv4 examples

# Localhost (loopback address)
127.0.0.1 localhost

# Local development
127.0.0.1 myapp.local
127.0.0.1 api.myapp.local

# Blocking a domain (redirect to nowhere)
0.0.0.0 distracting-site.com
0.0.0.0 www.distracting-site.com

# Point to specific server
192.168.1.100 staging.example.com
203.0.113.50 production.example.com

Common IPv4 addresses in hosts files

• 127.0.0.1: Localhost (your own machine)
• 0.0.0.0: Non-routable address (commonly used for blocking)
• 192.168.x.x: Private network range (local network)
• 10.x.x.x: Private network range
• 172.16.x.x - 172.31.x.x: Private network range

IPv6 address format

IPv6 addresses use hexadecimal notation with colons as separators. They're longer and more complex than IPv4 addresses but offer many more possible addresses.

IPv6 syntax rules

• Uses hexadecimal digits (0-9, a-f)
• Separated by colons (:)
• Can be compressed using :: to represent consecutive zeros
• Case-insensitive (though lowercase is conventional)

Standard IPv6 examples

# IPv6 localhost
::1 localhost

# Full IPv6 address
2001:0db8:85a3:0000:0000:8a2e:0370:7334 example.com

# Compressed IPv6 (using ::)
2001:db8:85a3::8a2e:370:7334 example.com

# IPv6 with port-like notation (not used in hosts file)
# Note: Ports are not part of hosts file entries

IPv6 localhost

The IPv6 equivalent of 127.0.0.1 is ::1. For maximum compatibility, many developers include both:

127.0.0.1 localhost
::1 localhost

Comments and organization

Comments are essential for maintaining readable and organized hosts files, especially as they grow larger.

Comment syntax

# This is a comment - entire line is ignored
127.0.0.1 example.com # Inline comments work but are less reliable

# Section header
# ===================
# LOCAL DEVELOPMENT PROJECTS
# ===================

127.0.0.1 project1.local
127.0.0.1 project2.local

# Client A - Production staging
192.168.1.50 staging.client-a.com
192.168.1.50 api.staging.client-a.com

Best practices for comments

1. 1Use section headers to organize entries by project, client, or purpose
2. 2Document IP addresses when pointing to specific servers
3. 3Note dates for temporary entries that need cleanup
4. 4Explain non-obvious entries to help future you or team members

Multiple domains and aliases

You can map multiple domain names to the same IP address on a single line. This is useful for:

• www and non-www versions
• Multiple subdomains
• Domain aliases

Examples of multiple domains

# Multiple domains on one line
127.0.0.1 example.com www.example.com api.example.com

# Separate entries (also valid, sometimes clearer)
127.0.0.1 example.com
127.0.0.1 www.example.com
127.0.0.1 api.example.com

# Common pattern: www and non-www
127.0.0.1 mysite.local
127.0.0.1 www.mysite.local

When to use multiple domains vs. separate entries

Use multiple domains on one line when:

• Domains are clearly related (www and non-www)
• You want to keep related entries together
• The line doesn't become too long

Use separate entries when:

• You might want to change one domain's IP independently
• Entries are for different projects/clients
• You want better readability and organization

Common patterns and use cases

Local development pattern

# ===================
# LOCAL DEVELOPMENT
# ===================

# Main application
127.0.0.1 myapp.local
127.0.0.1 www.myapp.local

# API endpoints
127.0.0.1 api.myapp.local
127.0.0.1 api-v2.myapp.local

# Admin panel
127.0.0.1 admin.myapp.local

# CDN/Assets
127.0.0.1 cdn.myapp.local
127.0.0.1 assets.myapp.local

Multi-environment pattern

# ===================
# DEVELOPMENT
# ===================
127.0.0.1 dev.example.com
127.0.0.1 api.dev.example.com

# ===================
# STAGING
# ===================
192.168.1.100 staging.example.com
192.168.1.100 api.staging.example.com

# ===================
# LOCAL TESTING
# ===================
127.0.0.1 test.example.com

Blocking pattern

# ===================
# BLOCKED SITES
# ===================
0.0.0.0 distracting-site.com
0.0.0.0 www.distracting-site.com
0.0.0.0 api.distracting-site.com

# Block advertising domains
0.0.0.0 ads.example.com
0.0.0.0 tracking.example.com

Formatting best practices

Consistent spacing

While the hosts file accepts any amount of whitespace, consistency improves readability:

# Good: Consistent spacing
127.0.0.1 example.com
192.168.1.100 staging.example.com

# Also good: Using tabs for alignment
127.0.0.1	example.com
192.168.1.100	staging.example.com

# Avoid: Inconsistent spacing (harder to read)
127.0.0.1 example.com
192.168.1.100 staging.example.com

File organization

# ===================
# SYSTEM DEFAULTS
# ===================
127.0.0.1 localhost
::1 localhost
255.255.255.255 broadcasthost

# ===================
# PROJECT: E-COMMERCE APP
# ===================
127.0.0.1 shop.local
127.0.0.1 api.shop.local
127.0.0.1 admin.shop.local

# ===================
# PROJECT: BLOG PLATFORM
# ===================
127.0.0.1 blog.local
127.0.0.1 cms.blog.local

Common syntax errors and how to fix them

Error: Missing whitespace

Incorrect:

127.0.0.1example.com

Correct:

127.0.0.1 example.com

Error: Invalid IP address

Incorrect:

999.999.999.999 example.com # Invalid IPv4 (numbers > 255)

Correct:

127.0.0.1 example.com

Error: Wildcard usage

Incorrect:

127.0.0.1 *.example.com # Wildcards not supported

Correct:

127.0.0.1 example.com
127.0.0.1 www.example.com
127.0.0.1 api.example.com

Error: Port numbers

Incorrect:

127.0.0.1:3000 example.com # Ports not part of hosts file syntax

Correct:

127.0.0.1 example.com # Port specified in application, not hosts file

Error: Protocol prefix

Incorrect:

http://127.0.0.1 example.com # No protocol in hosts file

Correct:

127.0.0.1 example.com

Advanced formatting techniques

Using tabs for alignment

Many developers prefer tabs for consistent alignment:

127.0.0.1	localhost
192.168.1.100	staging.example.com
10.0.0.50		api.staging.example.com

Grouping related entries

# Frontend domains
127.0.0.1 app.local
127.0.0.1 www.app.local

# Backend domains
127.0.0.1 api.local
127.0.0.1 api-v1.local
127.0.0.1 api-v2.local

# Database/admin
127.0.0.1 admin.local
127.0.0.1 db.local

Testing your hosts file syntax

After editing your hosts file, verify your syntax is correct:

Method 1: Ping test

ping example.local
# Should return: PING example.local (127.0.0.1)

Method 2: nslookup

nslookup example.local
# Should show your configured IP address

Method 3: dig command

dig example.local
# Check the ANSWER section for your IP

Platform-specific considerations

macOS

• File location: /etc/hosts
• Requires sudo to edit
• Flush DNS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
• .local domains may use Bonjour/mDNS (use .test instead)

Linux

• File location: /etc/hosts
• Requires sudo to edit
• Flush DNS: sudo systemd-resolve --flush-caches (systemd) or restart network service

Windows

• File location: C:\Windows\System32\drivers\etc\hosts
• Requires administrator privileges
• Flush DNS: ipconfig /flushdns

Tools for hosts file management

While you can edit the hosts file manually, using a dedicated tool offers several advantages:

• Syntax validation: Catch errors before they cause problems
• Visual interface: Easier to read and organize entries
• Quick enable/disable: Toggle entries without editing the file
• DNS flush integration: Automatically flush cache after changes
• Backup and restore: Safely experiment with configurations

ToggleHosts is a modern macOS application designed specifically for hosts file management. With an intuitive interface, automatic syntax validation, and one-click DNS flushing, it makes working with the hosts file effortless. Try ToggleHosts today for just $4.99 and streamline your local development workflow.

Related hosts file guides

For the broader concepts behind this syntax, read the complete hosts file guide. If you are editing the file on macOS, follow the Mac hosts file editing tutorial and use the troubleshooting guide when entries do not resolve as expected.

Conclusion

Mastering the /etc/hosts file syntax and format is essential for efficient local development and network management. By following the rules and best practices outlined in this guide, you can create well-organized, maintainable hosts file configurations that serve your development needs effectively.

Remember:

• Use proper spacing between IP and domain
• One entry per line
• No wildcards or protocols
• Organize with comments
• Test your changes
• Flush DNS cache after modifications

Whether you're managing multiple local projects, testing staging environments, or blocking distracting sites, a well-formatted hosts file is a powerful tool in your development arsenal.

Sources and further reading

• How DNS works (Cloudflare Learning)
• The hosts file explained (Wikipedia)
• hosts(5) manual page (man7.org)