hostsVN: a hosts file list that targets Vietnamese ad domains

What hostsVN actually publishes

hostsVN is a data repository, not a program. It maintains a hosts file whose entries point Vietnamese ad and tracking domains at a blocking address, so that a request never reaches the ad server. The project was created on 02 jul 2018 according to the badge in the README, and it is described simply as hosts block ads of Vietnamese.

The primary artefact is a single file named hosts at the root of the repository, published at a raw URL:

https://raw.githubusercontent.com/bigdargon/hostsVN/master/hosts

Several variants sit under the option/ directory, and the choice between them is the real decision a user makes. There is a hosts-iOS file for jailbroken iOS devices, a hosts-VN file that contains only domains in Vietnam, a domain.txt file that contains only domain names with no address mapping, and a domain-VN.txt file that does the same restricted to Vietnamese domains.

The domain-only files are worth understanding because they are the ones meant to be pasted into other tools rather than dropped into a system hosts file. The filters/ directory holds a separate adservers-all.txt used by the AdGuard apps, and the extensions/ directory holds per-client configuration files.

There is no installer, no daemon, and no update mechanism in the repository. You fetch a file and point something at it.

One list, many client formats

A hosts file only works if the operating system or application reads it, and that differs sharply between iOS and Android. The project therefore ships the same underlying domain data in several formats.

For iOS, the documented pairings are AdGuard Premium or Pro with the filters/adservers-all.txt file, Adblock with the option/domain.txt file, Surge with the option/hostsVN-surge.conf file, Shadowrocket with the option/hostsVN-shadowrocket.conf file, and Quantumult X with the option/hostsVN-quantumultX.conf file. There is also a jailbreak path using the option/hosts-iOS file, and the project notes that Adguard is needed as well to block ads in Safari.

For Android without root, the hosts file is used with apps that consume it locally: Blokada, DNS66, Nebulo, RethinkDNS with its firewall, Virtual Hosts, and BlockAds.

For rooted Android, the route is Adaway, and the list to add is not hosted in this repository at all but at abpvn.com:

https://abpvn.com/android/abpvn.txt

That difference is worth noticing. The main hosts file is a GitHub raw URL, while the Adaway subscription comes from a separate domain, so a rooted Android user depends on two different hosts for the same project.

The project also points readers to a wiki page for the detailed guides rather than documenting every step inline.

How the list is built and what the repository layout reveals

The top level of the repository gives away the pipeline. There is a source/ directory, a tmp/ directory, a json/ directory, an extensions/ directory, an option/ directory, a filters/ directory, and a script named makefile.sh at the root.

That layout describes a generator rather than a hand edited file. The source directory holds the origin of the data, tmp/ is clearly scratch space, json/ suggests structured intermediate data, and makefile.sh is the script that ties it together and emits the hosts file and the client specific configurations. The extensions/ directory holds the per-application configurations, while option/ holds the curated variants a user actually downloads.

Because the pipeline is scripted, the list is reproducible in a way a manually curated file would not be. It also means the domain set is assembled from sources and rules that the project documents in its wiki, rather than being a single curated set you can read top to bottom.

For an engineer, the practical consequence is that hostsVN behaves like a subscription feed with a build step, and it should be consumed on a schedule rather than vendored into a repository as a one-off copy.

Fetching and refreshing the file on your own machine

Because the artefacts are plain files served over HTTPS, using them from a shell is a matter of downloading and pointing a client at a URL. The list of URLs you need depends on the client, and the project documents one per client.

The main hosts file is served as a plain text document over HTTPS, so any client that accepts a subscription URL, or any scheduled download on your side, can consume it directly:

https://raw.githubusercontent.com/bigdargon/hostsVN/master/hosts

Two choices behind that address matter. The master branch is used rather than a tag, because the repository has no GitHub releases, so master is the only addressable current version of the list. And any local download is a snapshot, so it ages the moment it lands on disk.

For the per-application files, the same pattern applies with the option/ or filters/ path swapped in, for example the Surge configuration at option/hostsVN-surge.conf or the AdGuard list at filters/adservers-all.txt. The project documentation points to the wiki for the exact steps each client expects, since the format differs per application and a hosts file dropped into a Surge configuration is not the same operation.

Keep the download on a schedule if the domains matter to you. A stale ad block list is worse than none, because it keeps the cost of lookups while missing new domains.

The hosts file route versus DNS filtering

The project offers a specific mechanism, and it is worth being explicit about what it does and does not do.

A hosts file entry resolves a domain name locally, so the browser or app never issues a network request for that name. The strength of that approach is that it needs no server, no root on Android when you use one of the listed local DNS apps, and it works at the system level for anything on the device. The weakness is that it is name based. It cannot filter by category, cannot inspect a URL path, cannot log what was blocked, and cannot be updated except by fetching a new file.

DNS filtering, which is what the AdGuard apps on iOS and the local DNS apps on Android do, works on the query or request level rather than the name level, which is why the project pairs those clients with a domain list or a filter file instead of the hosts file itself.

So the choice inside hostsVN is between two mechanisms. Use the hosts file when you want a system-wide block with no daemon. Use the AdGuard, Surge, Shadowrocket or Quantumult X configuration when you want the block to live inside a client that already has category rules, logging and its own update schedule. What the project does not offer is a self-hosted resolver, so anyone who wants centralised logging across a network is outside its scope.

Where hostsVN falls short

The first limitation is the scope of the data. The project is built around Vietnamese ad domains, and even the full list carries a VN flavour, so it is not a general purpose global ad blocking list. The option/hosts-VN file is narrower still, restricted to domains hosted in Vietnam. Anyone expecting coverage of international ad networks from this repository alone will be disappointed.

The second limitation is update mechanics. There are no releases, no version tags, no changelog and no rollback path, so you cannot pin a known good state of the list and you cannot easily tell what changed between two fetches. The JSON directory in the tree suggests structured data is produced, but the documentation does not describe a stable schema you could diff against.

The third is platform coverage on iOS. The project explicitly says Adguard is also needed to block ads in Safari, and the hosts file route on iOS requires a jailbroken device. That is a narrow path, and it pushes most iOS users toward the filter list files rather than the hosts file itself.

The fourth is legal and operational rather than technical. A blocklist that names third party domains creates questions about who maintains the entries and what happens when an entry is wrong, and the project does not document a dispute or removal process.

Licence, maintenance and the state of the tree

The project is released under the MIT licence, with the text in the LICENSE file. That permits reuse and redistribution of the list with the copyright notice retained, which matters if you want to publish a derived list or vendor it into a device image. Read the LICENSE file yourself for the exact conditions.

The repository is not archived and the last push was on 2026-10-13, so the data is being regenerated rather than abandoned. The topics list names the clients the project supports directly, including adguard, adblock, surge, quantumult, quantumultx, shadowrocket and android, which matches the configuration files described above.

There is no packaged release to consume, so your options are to fetch raw files or to subscribe a client to a URL. Because the raw URLs point at the master branch, a client that polls them will pick up new entries automatically, and one that pulls a local copy will not.

The homepage is a GitHub Pages site at bigdargon.github.io/hostsVN, and the project uses a wiki for the step by step guides. Those two are where the per-client instructions live, so a new user should read them before assuming the main hosts file is the right input for their app.

Editorial conclusion

hostsVN suits someone in Vietnam who wants ad blocking without running a full DNS resolver, and who already uses one of the listed apps, since the project ships per-app configurations rather than an installer. It does not suit anyone who wants a blocking solution that also logs, filters by category or updates on its own, because the list is a static file you fetch and apply. Before adopting it, check the domains you care about against the option/domain.txt list, confirm your platform is one of the ones the project lists, and fetch the raw file from the master branch rather than pinning a commit, since the repository publishes no releases.

Frequently asked questions

Official sources

1. bigdargon/hostsVN on GitHub
2. Issues
3. License: MIT
4. Project website
5. README