hostfile

繁體中文 | 日本語 | 한국어

A cross-platform CLI tool for managing your hosts file with ease.

Designed to be simple enough that anyone can use it — just copy-paste a command and hit Enter.

Features

• Add / Remove — manage IP-domain mappings, auto-merge same IP entries
• Enable / Disable — toggle entries without deleting them (per-IP or per-domain granularity)
• Search / Show — query and display managed entries with colored, aligned output
• Apply / Merge — import from files or stdin, auto-detects JSON and hosts format with validation
• JSON I/O — show --json for export, apply - / merge - for import via pipeline
• Save / Load — snapshot and restore your managed entries
• Clean — clear all managed entries in one command
• Managed block isolation — never modifies entries you wrote by hand
• Automatic privilege escalation (sudo / doas / gsudo)
• IPv4 + IPv6 support (including zone IDs)
• Shell completion (bash, zsh, fish, powershell)
• Cross-platform: macOS, Linux, Windows

How It Works

hostfile only touches its own managed block inside your hosts file — it never modifies entries you wrote by hand:

# Your original content — hostfile won't touch this
127.0.0.1  localhost

#### hostfile >>>>>
192.168.1.100  web.company.local api.company.local
#[disable-ip] 192.168.1.200  minio.company.local
#[disable-domain] dockerhand.company.local 192.168.1.100
#### hostfile <<<<<

Installation

Quick Install

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.ps1 | iex

To update, run the same command again. To uninstall:

curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/uninstall.sh | sh

irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/uninstall.ps1 | iex

Windows Note: hostfile modifies the system hosts file, which requires administrator privileges. On Windows 11 24H2+, sudo is built-in and hostfile will use it automatically. On older versions, install gsudo or run PowerShell as Administrator.

Install gsudo:

# PowerShell one-liner
irm https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex

# Or via Scoop
scoop install gsudo

Package Managers

Platform	Command
Homebrew (macOS / Linux)	brew install vulcanshen/tap/hostfile
Scoop (Windows)	scoop bucket add vulcanshen https://github.com/vulcanshen/scoop-bucket && scoop install hostfile
Debian / Ubuntu	sudo dpkg -i hostfile_<version>_linux_amd64.deb
RHEL / Fedora	sudo rpm -i hostfile_<version>_linux_amd64.rpm

.deb and .rpm packages can be downloaded from the Releases page. Replace <version> with the version number (e.g. 1.2.0). For ARM64 systems, use linux_arm64 instead of linux_amd64.

Commands

Command	Description
init	Take over the current hosts file — backs up as "origin", reformats all entries into managed block
add <ip> <domain1> [domain2...]	Add domains to an IP, auto-merge if the IP already exists
remove <ip|domain>	Remove an IP (entire line) or a single domain
search <ip|domain>	Search the managed block — IP returns domains, domain returns IP
show	Show all entries in the managed block (colored, aligned)
show --json	Output active entries as JSON
show <name>	Show the contents of a saved snapshot
enable <ip|domain>	Re-enable a disabled entry
disable <ip|domain>	Disable an entry without deleting it
apply <file | ->	Replace the managed block with content from a file or stdin (supports JSON)
merge <file | ->	Merge content from a file or stdin into the managed block (supports JSON)
clean	Clear all entries from the managed block
save <name>	Save the managed block as a snapshot to ~/.hostfile/<name>.hostfile
list	List all saved snapshots
load <name>	Load a saved snapshot into the managed block
delete <name>	Delete a saved snapshot
version	Print the version number

Global Flags

Flag	Description
--hosts-file <path>	Path to hosts file (default: /etc/hosts or C:\Windows\System32\drivers\etc\hosts)

Show Flags

Flag	Description
--json	Output active entries as JSON ({"ip": ["domain1", "domain2"]})

Usage Examples

# First time setup — take over your existing hosts file
hostfile init

# Add entries
hostfile add 192.168.1.100 web.local api.local

# Show managed entries
hostfile show
hostfile show --json            # JSON output (active only)

# Search
hostfile search web.local
hostfile search 192.168.1.100

# Disable / Enable
hostfile disable web.local        # disable a single domain
hostfile disable 192.168.1.100    # disable an entire IP line
hostfile enable web.local

# Remove
hostfile remove web.local          # remove a domain
hostfile remove 192.168.1.100     # remove an IP and all its domains

# Import from file
hostfile apply hosts.txt           # replace managed block
hostfile merge hosts.txt           # merge into managed block

# Import from JSON
hostfile apply config.json         # auto-detects JSON format
hostfile show --json | hostfile apply -  # pipe between instances

# Save / Load
hostfile save my-snapshot
hostfile list
hostfile show my-snapshot
hostfile load my-snapshot
hostfile delete my-snapshot

# Clear everything
hostfile clean

# Restore original hosts file (before init)
hostfile load origin

# Use a custom hosts file (for testing or dry-run)
hostfile show --hosts-file /tmp/test.hosts

Shell Completion

# Zsh
mkdir -p ~/.zsh/completions
hostfile completion zsh > ~/.zsh/completions/_hostfile
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

# Bash
hostfile completion bash > /etc/bash_completion.d/hostfile

# Fish
hostfile completion fish > ~/.config/fish/completions/hostfile.fish

# PowerShell
hostfile completion powershell > hostfile.ps1

Advanced

Environment Variable	Description
HOSTFILE__HOSTS_FILE	Override the default hosts file path. When set, all commands use this path instead of /etc/hosts.

License

GPL-3.0