StevenBlack/hosts: a unified hosts file aggregator for ad, malware and category blocking

What StevenBlack/hosts actually solves, and for whom

Blocking ads and malware domains at the DNS layer means editing one file per machine, and every list you find has its own format, its own duplicates and its own dead entries. This project takes several curated sources, merges them, removes duplicates and publishes the result as a hosts file. The README calls the repository "a hosts file aggregator" and states that it consolidates reputable hosts files into a unified file with duplicates removed.

The audience is narrow but real: someone who controls the machines on their network and wants a file, not a service. A home router running dnsmasq or unbound, a laptop with an editable hosts file, a small office that would rather not run a filtering appliance. The repository ships 31 variants in addition to the base file, so the same build covers a plain adware and malware list and a list with porn, gambling, social or fake news categories folded in. The base variant is listed at 79,962 unique domains; the porn variant at 156,146.

It is not a browser extension and not a DNS resolver. It produces a text file. Everything about deployment, refresh and rollback is left to whatever consumes that file.

The data flow: sources in, one deduplicated hosts file out

The repository layout tells most of the story. Source lists live under data/, the extension definitions under extensions/, and the published output is the file named hosts at the repository root. updateHostsFile.py is the build entry point; makeHosts.py is wired to the npm start script, and updateReadme.py regenerates the documentation tables. There is also a testUpdateHostsFile.py test module, run through the npm test script.

The build reads each source, normalises entries to hosts-file syntax, drops duplicates, and writes the merged result. The README is explicit about ownership of content: issues about the content of a produced hosts file should go to the data source that contributed it, with contact information for each source in the hosts/data/ directory, except for changes to hosts/data/StevenBlack/hosts. That is an unusual and honest boundary. The aggregator maintains the merge, not the individual blocklists.

Because the output is a plain file, the mechanism has no runtime component. There is no daemon, no query log, no per-client policy. A blocked domain resolves to a loopback address and the connection fails. Category variants are just different merges of the same machinery, which is why the unique-domain counts differ so much between them.

Installing StevenBlack/hosts and blocking your first domain

Most people should not clone the repository at all. The README opens with a warning that cloning can take a long time and that you probably want the latest version rather than the history since 2018, recommending a shallow clone. For a single machine, the simpler path is to fetch the published file directly, as the README's raw link does:

curl -o hosts https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

That downloads the base unified file (adware plus malware). If you want a category variant, substitute the path from the variants table, for example alternates/porn/hosts. The README also lists a non-GitHub mirror at sbc.io for hosts file managers such as Hostsman for Windows that do not work with GitHub download links.

To build it yourself, the repository is Python. requirements.txt pins requests and flake8. The npm scripts map to the Python entry points:

npm install
npm start
npm test

npm start runs python3 makeHosts.py and npm test runs python3 testUpdateHostsFile.py. A Dockerfile is also provided, based on python:3-alpine, which copies the repository to /hosts, installs requirements.txt and sets IN_CONTAINER=1.

Before replacing a live hosts file, keep a copy. The README does not document a rollback procedure, so the safe move is to save the original file yourself and restore it if something breaks.

Where the hosts file approach fails

The hosts file has no wildcard support in its classic form. A blocklist entry blocks the exact hostname written in the file; subdomains need their own entries. That is a structural limit of the mechanism, not a defect in this project, and it is why blocklists grow to tens of thousands of domains.

Second, coverage is uneven across the variants. The README's table lists the social-only variant at 3,808 unique domains and the fake news-only variant at 2,187, against 79,962 for the base file. If you enable the social extension expecting the same depth as the adware and malware lists, you will not get it. The counts are published, so this is checkable rather than hidden, but it is worth reading the table before choosing a recipe.

Third, this is the wrong tool for anything that needs visibility. There is no query log, no per-device policy and no reporting. On a network with roaming laptops, a file-based blocklist only applies to machines where the file was actually installed. And if a blocked domain is also needed for a legitimate service, you are editing a generated file that will be overwritten on the next update unless you keep your additions separate. The repository provides whitelist.example and myhosts.example for exactly that purpose, which is a hint that hand-editing the generated output is not the intended workflow.

How it differs from Pi-hole and DNS-level blockers

Pi-hole and similar DNS sinkholes answer queries themselves. They run as a resolver, log every query, and let you apply policy per client. StevenBlack/hosts produces a file that some other resolver reads. The difference is where the state lives: in a running service with a database and an admin interface, or in a text file you copy around.

The practical consequences run in both directions. A Pi-hole gives you the query log and per-device rules that this project has no equivalent for. This project gives you a file you can diff, version and drop onto a machine with no daemon at all, and it publishes category variants as separate artifacts rather than as checkbox options in a UI.

If you already run a DNS resolver, the two combine: the resolver can consume the published file as one of its sources. That is the common deployment, and it is consistent with the repository's own description of itself as an aggregator rather than a filter.

Maintenance cadence, upgrades and the MIT licence

The last push was on 2026-09-09, and releases 3.16.111 through 3.16.113 landed between 2026-08-31 and 2026-09-09. The README's own header states the file was last updated on September 09 2026. The repository is not archived. That cadence matters because blocklists decay: an aggregator that stops merging stops being useful even if the code still runs.

Upgrading means re-fetching or rebuilding. If you consume the raw file from GitHub, you get whatever the current build produced, and there is no version pin in the URL. If you build locally, package.json carries the version (3.16.114 in the checked-in file, ahead of the latest release listed at 3.16.113) and release-it is the release tooling, with release-it as the only devDependency. The test script exists, so a local build can be validated before you deploy it.

The licence is MIT. That permits reuse and redistribution with the licence and copyright notice retained. It does not resolve the licensing of the upstream sources that contribute entries; the README points to the data sources' own contact information in hosts/data/, and anyone redistributing the merged output commercially should read those sources rather than assume the MIT label covers every entry. That is a question for a lawyer, not for this article.

Editorial conclusion

Adopt it if you want a single maintained hosts file with category variants and you are comfortable editing a local file or running a Python build. Skip it if you need per-request logging or filtering on a network with roaming devices. Before rolling it out, check the unique-domain count for the variant you want, confirm the raw URL you will fetch, and test one blocked domain on a single machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. StevenBlack/hosts on GitHub