A tool to build and maintain /etc/hosts along-side hosts list sources
Go to file
2017-05-24 10:44:38 -04:00
buildhosts Clean up formatting and add missing dependencies to buildhosts 2017-05-24 10:44:38 -04:00
LICENSE Use full name in license file 2014-11-19 00:16:02 -05:00
p2p-to-hosts Clean up formatting and add missing dependencies to buildhosts 2017-05-24 10:44:38 -04:00
README.md Add dependency check, fix some bugs, use more builtins and better practices, add colour to help output, update README for clarity, and remove the man page 2015-02-02 08:31:09 -05:00


Download and use custom hosts sources to build /etc/hosts


  • buildhosts build: generate /etc/hosts using /etc/hosts.core and the configured sources
  • buildhosts revert: remove lists imported from hosts list sources and restore /etc/hosts
  • buildhosts help: display the help

Configure Hosts Sources

  1. Running buildhosts build for the first time will move /etc/hosts to /etc/hosts.core and create /etc/hosts.sources with a set of default hosts sources that focus on ad-blocking, and these will be downloaded before a new /etc/hosts is then created using /etc/hosts.core and the contents of the hosts sources.
  2. Once this is finished, you can add/edit/delete or comment (lines starting with #) hosts sources in /etc/hosts.sources, and running buildhosts build again will re-create /etc/hosts using your updated sources.

Remove Hosts Sources

  1. To disable the configured hosts lists and restore your original configuration, run buildhosts revert and /etc/hosts.core will be moved back to /etc/hosts (/etc/hosts.sources will need to be manually deleted).

Environment Variables

These variables can be configured before running buildhosts to run with custom locations

  • HOSTS_DIR: Directory containing the hosts file (default: /etc/)
  • HOSTS_SYSTEM: The system hosts file (default: $HOSTS_DIR/hosts)
  • HOSTS_CORE: The file containing the custom hosts configuration (default: ${HOSTS_SYSTEM}.core)
  • HOSTS_SOURCES: The file containing a list of hosts sources to download (default: ${HOSTS_SYSTEM}.sources)
  • HOSTS_WHITELIST: The file containing a list of domains to skip when parsing $HOSTS_SOURCES (default: ${HOSTS_SYSTEM}.whitelist)


  • The p2p-to-hosts script included in this repo can be used to convert blocklists in p2p format to hosts format (usable with this package).


Written by Kevin MacMartin:


Released under the MIT license.