AdGuard Filters: How AdGuard's Blocklists Are Built and Maintained

What These Filter Lists Are and Where They Are Used

AdguardTeam/AdguardFilters contains the source of the filter lists that ship with AdGuard's browser extensions, desktop applications, and mobile apps. The README describes each filter as "a set of text-based rules that AdGuard apps and programs use to filter out advertisements and privacy-invasive content like banners, pop-ups, and trackers."

The repository is also explicitly listed as a source for uBlock Origin, one of the most widely used browser extensions for content blocking. The filter lists are text files where each line describes either a domain, a URL pattern, or an element-hiding rule in AdGuard's extended filter syntax.

The repository is where issues are filed when ads slip through or when a legitimate site is incorrectly blocked. It serves two audiences: end users who want to report problems, and contributors who propose rule changes directly through the issue tracker and pull requests. AdGuard's filter engineers review incoming proposals and merge accepted rules into the lists.

Repository Layout: Regions, Purposes, and Base Filters

The top-level directory reveals how the filter lists are divided. Regional filters cover languages and markets with dedicated directories: ChineseFilter, CyrillicFilters, DutchFilter, FrenchFilter, GermanFilter, ItalianFilter, JapaneseFilter, PolishFilter, SpanishFilter, and TurkishFilter. Each regional filter targets ad networks and trackers that are specific to that market.

Purpose-specific filters address different tracking vectors: SpywareFilter covers tracking and data collection scripts, SocialFilter handles social media widgets and share buttons, MailTrackingFilter targets email tracking pixels, TrackParamFilter strips tracking parameters from URLs, and MobileFilter addresses ad formats common in mobile browsers.

AnnoyancesFilter and UsefulAdsFilter serve opposing roles. AnnoyancesFilter removes non-advertising clutter like cookie consent banners and newsletter popups. UsefulAdsFilter exists to allow certain categories of advertising that AdGuard has judged acceptable under its filter policy.

BaseFilter is the primary general-purpose list. ExperimentalFilter holds rules under review before they are promoted to a stable list.

All filter files are plain .txt files, which means they can be reviewed, diffed, and audited without any special tooling.

Contributing Rules and Setting Up the Linting Toolchain

The repository uses Node.js and aglint, AdGuard's own filter-list linting tool, to validate rule syntax before merge. The package.json requires Node.js 22 or later and npm 11.10.0 or later.

The aglint script runs the validator with caching enabled, pointing it at all .txt files in the repository. The cache stores results by content hash, so subsequent runs only re-check files that have changed since the last validation pass. A separate markdownlint script validates documentation files. The package.json lint script chains both together: it runs aglint and then markdownlint in sequence, so a single lint pass covers both filter syntax and documentation. A husky pre-commit hook (configured in the repository) runs lint-staged automatically when a contributor attempts a commit, catching syntax errors before they reach the pull request.

For users who only want to report a missed ad or false positive, the README links to a reporting tool at agrd.io/report. Writing and testing rules requires reading the official filtering-rules documentation before submitting suggestions in issues.

False Positives and the Cost of Aggressive Rules

The primary failure mode for any filter list is the false positive: a rule that blocks content on a legitimate site or breaks site functionality. The README acknowledges this as an ongoing concern: it explicitly mentions false positives alongside missed ads as the two main categories of issues the community reports.

Aggressively written rules can break login flows, payment forms, comment sections, or embedded video players on sites that share infrastructure with ad networks. A rule targeting a CDN domain might block fonts or scripts needed for the site to function. The issue tracker for this repository reflects the ongoing work of balancing coverage against collateral damage.

The ExperimentalFilter exists partly to contain rules that have not yet been proven stable. Users who enable ExperimentalFilter in their AdGuard configuration accept a higher risk of false positives in exchange for earlier coverage of newly identified tracking techniques.

For corporate environments where breakage is unacceptable, using only the BaseFilter with minimal regional additions is the conservative approach. The repository does not document a recommended subset for enterprise deployments.

EasyList as the Alternative Filter Ecosystem

EasyList is the most widely deployed independent filter list, used as a primary source by AdBlock Plus, uBlock Origin, and many other blockers. The difference in approach is governance: EasyList is community-maintained under a voluntary contributor model, while AdGuard Filters is maintained by a commercial company (AdGuard Software Ltd., registered in Cyprus) whose engineers review and merge rule changes as part of their paid work.

In practice, this affects response time for newly identified ad networks and the reliability of the review process. A commercial team with dedicated filter engineers can push changes on a tighter schedule than a volunteer community, though the community model allows for a broader range of contributors with regional knowledge. Both projects are publicly visible and accept external contributions through their respective issue trackers.

The two filter sets are not mutually exclusive. AdGuard applications can load both AdGuard Filters and EasyList simultaneously. Overlap between the two lists introduces some redundancy but is generally harmless.

Licence and Distribution

The repository is licensed under GPL-3.0-only. The filter lists are text files, and distributing modified copies of them requires releasing the modifications under the same GPL-3.0 terms. This is relevant for developers who want to ship a custom blocker that forks and extends AdGuard's filter lists: the GPL requires making any changes available under the same licence.

AdGuard's filter policy, linked in the README, governs which categories of content the filters block and allow. The policy is published at adguard.com/kb and is not part of the repository itself. Decisions about whether a specific ad format or tracking technique belongs in the filters are governed by that policy document, not by community consensus in pull requests.

Editorial conclusion

AdGuard Filters is the right resource for developers integrating AdGuard filter lists into custom blockers, for users who want to report missed ads or false positives directly to the maintainers, and for contributors who want to write and test their own filtering rules. It is not a standalone blocking application and will not work without a compatible blocker like an AdGuard product or uBlock Origin. Before relying on any subscription URL, verify it against AdGuard's official documentation site rather than informal sources, since unofficial mirror URLs can lag behind the canonical lists.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository