Skip to main content
CleanWeb
Hosts file

Use a hosts file without wrecking your machine's network settings.

A hosts file affects one device. It uses exact host mappings, not wildcard rules. This guide covers a safe backup-first install on Windows, macOS, and Linux, plus rollback and the cases where hosts blocking simply will not work.

Never replace the whole system hosts file with a blocklist

CleanWeb's hosts download contains only generated block entries. It is not a complete system file. Replacing /etc/hosts or the Windows hosts file with it can remove localhost mappings and break local services. Back up the original and append the new entries instead.

Before you start

  • Generate and download a hosts-format configuration.
  • Make sure you can obtain administrator or root access on the device.
  • Back up the existing hosts file before editing it.
  • Have another way to remove the entries if the device misbehaves. A recovery shell or second account is useful on Linux and macOS.

A hosts file is local. Installing it on a laptop does not filter a phone, a television, or the rest of the network. Use AdGuard Home or Pi-hole if you need network-wide DNS filtering.

What the generated file does

Each line maps a hostname to an IP address. CleanWeb uses 0.0.0.0 example.org, a common way to point a name at an unusable address. This is a host mapping, not a DNS blocklist entry: it only affects the machine where the hosts file is installed.

Hosts entries are exact. Adding example.org does not automatically add ads.example.org or deep.sub.example.org. CleanWeb's host list includes the exact hostnames in its source snapshot; it cannot turn hosts syntax into wildcard matching.

The generated file also contains a complete comment header with source names, links, and license notes. Comment lines beginning with # are ignored by the operating system.

Windows

  1. Open File Explorer and navigate to C:\Windows\System32\drivers\etc\.
  2. Copy hosts to a backup file outside that directory, for example hosts.backup-cleanweb. Keep the backup somewhere you can restore from with administrator access.
  3. Open the original hosts file in a plain-text editor with administrator privileges. Windows may offer Notepad when you choose “Open with.” Do not use a word processor that adds formatting.
  4. Append the CleanWeb entries to the end of the existing file. Do not remove the existing localhost or local-network entries. Keep one mapping per line.
  5. Save the file without changing its name or extension. The filename is exactly hosts.
  6. Flush the DNS cache so the change is picked up promptly (see the section below).

If Windows refuses to save, the editor was not started with sufficient privileges. Close it and reopen the editor as administrator. A permissions error is not a reason to disable Windows security features globally.

macOS and Linux

The system file is /etc/hosts. Make a backup first, then edit the original with an editor that preserves plain text. The exact editor is your choice; the important part is appending entries and keeping the original localhost mappings intact.

# Back up first
sudo cp /etc/hosts /etc/hosts.backup-cleanweb

# Edit the live file
sudo nano /etc/hosts

Append the CleanWeb lines at the end, save, and exit. On systems managed by configuration management or an immutable filesystem, local edits may be overwritten or blocked; use the managed mechanism instead of fighting it.

Do not run a hosts file as a script. It is data. Review any blocklist before adding it, even when the source link looks familiar.

Flush the DNS cache

The operating system and applications can cache the old answer. Depending on the platform, use the command that matches your setup:

# Windows (Command Prompt)
ipconfig /flushdns

# macOS (recent versions)
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

# Linux with systemd-resolved (where available)
sudo resolvectl flush-caches

Linux distributions differ. Some use nscd, some use a different resolver or no system cache at all. Consult your distribution's documentation instead of assuming the systemd command applies. A browser may also have its own cache or secure DNS behavior.

Updating and reverting

Generate a new file and compare it with the current one before editing. Replace only the CleanWeb block, not the rest of the hosts file. If you keep the generated header, it is easy to see where the block begins, but the header is just a comment and does not enforce boundaries.

To revert, restore your backup and flush the DNS cache again. On Windows, if File Explorer will not let you overwrite the file, use an administrator editor to restore the backup contents. On macOS and Linux, replace the file with the backup using the appropriate privileges and then flush caches.

Limits and safety

A hosts file is a coarse, per-device tool. It does not provide network-wide control, automatic updates, wildcard matching, or protection from clients that bypass the operating system's resolver. A VPN, a browser's secure DNS setting, a proxy, or an app with its own resolver can ignore it.

A hosts entry with IPv4 0.0.0.0 targets IPv4 resolution. If an application reaches the same hostname over IPv6, behavior can differ. Do not treat a hosts block as a comprehensive security control.

Large hosts files can slow name resolution on some systems and make troubleshooting harder. Keep a backup, keep the source header, and remove entries you no longer need. CleanWeb's generated lists are bounded snapshots, not full upstream mirrors; review the source and license notes before redistributing them.

For platform details, see the hosts(5) manual page and your operating system's DNS documentation.