AdGuard Filters Registry: How AdGuard Rehosts and Recompiles Filter Lists

What the Registry Actually Does

AdGuard Filters Registry is not a filter list itself. It is the canonical repository that stores AdGuard's own filters and rehosted third-party lists. The README states that filters can be slightly modified to achieve better compatibility with AdGuard. The registry serves these lists via filters.adtidy.org. The target audience is twofold: AdGuard product maintainers who need a single source for filter subscriptions, and third-party filter authors who want their lists distributed to AdGuard users. The registry does not host arbitrary lists. It enforces an acceptance policy with specific rules, such as a minimum of 50 GitHub stars, at least 10 updates per month, and a public place for complaints. This is a curated registry, not an open upload service.

The Build Pipeline: Templates to Platform-Specific Outputs

The core mechanism is a build pipeline that compiles filter templates into platform-specific outputs. The README lists eight target platforms: Android, CLI, Extension, iOS, Mac, Mac v2, Mac v3, and Windows. Each filter directory contains a template.txt file, an exclude.txt file with regular expressions, and a metadata.json file. The compiler uses the template to produce the final filter version. Rules that match the exclusions in exclude.txt are omitted. The compiler also generates incremental patches, which are useful for reducing update size. The pipeline is not a simple copy. It transforms the template based on the target platform. This means a filter may behave differently on different AdGuard products, depending on what the compiler does with the template.

Getting It Running: Commands and Configuration

The README does not include explicit build commands. It references a compiler and documentation. What is clear is the directory structure. Filters live under filters/ for AdGuard filters and filters/ThirdParty/ for third-party lists. Each filter directory must contain template.txt, exclude.txt, and metadata.json. The metadata.json file includes required keys such as filterId, name, description, timeAdded, groupId, downloadUrl, and tags. Optional keys include deprecated, disabled, subscriptionUrl, and trustLevel. To add a filter, you would create a directory with these files and submit it for review. The acceptance policy is the practical gate. Without a GitHub repository with at least 50 stars, your filter is unlikely to be accepted. The README also mentions that filters with no support for a year are removed. This is a maintenance commitment, not a one-time upload.

Trust Levels: How AdGuard Limits Third-Party Rules

The trustLevel field in metadata.json is a distinctive feature. It can be low, high, or full. The README explains that low allows only low-risk rule types and is the default if not configured. High is for trusted third-party lists, but some rules are still permitted, meaning they may be disabled. Full allows all rule types, and only AdGuard's own filters have full trust at the moment. This is a direct control mechanism. The compiler uses trust levels to decide which rules are allowed. A third-party filter with a low trust level may have many of its rules stripped. This is a significant limitation for filter authors. You can write a filter that works in a browser, but AdGuard may disable parts of it based on trust. The README says trust can be re-reviewed and raised if the author improves the filter. That is the only path to looser restrictions.

The Acceptance Policy: A Barrier or a Filter?

The acceptance policy is explicit and detailed. It is not a vague guideline. The rules include: the filter must be oriented towards browser content blockers, must be legal, must have a public place for complaints, must have at least 50 GitHub stars if on GitHub, must be actively supported for at least 6 months, and must have at least 10 updates per month. There is also a rule about filters that intentionally block services based on the author's opinion. Those are not added or are removed. This policy serves two purposes. It keeps the registry clean of low-quality or abusive lists. It also creates a high bar for entry. For a small filter author, meeting 50 stars and 10 updates per month is not trivial. The policy also gives AdGuard the right to remove filters early under certain circumstances. This is a unilateral control, which is worth noting if you depend on the registry for distribution.

Wildcard Domain Expansion and Repository Compression

The README's table of contents lists sections titled Wildcard Domain Expansion and Repository Compression. Based on the names, wildcard domain expansion likely refers to a process that expands wildcard domains in filter rules into explicit domain lists. This could be a compatibility step, as some ad blockers do not support wildcard domains in the same way. Repository compression likely refers to the incremental patches mentioned earlier, which reduce the size of updates. If you need to understand these features, you would have to read the full README or the linked documentation in the repository.

Maintenance Costs and License Implications

The repository is licensed under LGPL-3.0. This is a copyleft license, but it is the Lesser GPL, which is designed for libraries. The README does not discuss licensing implications for filter lists themselves. Filter lists are data, not code, so the LGPL may not apply to the content of the filters. However, the build pipeline and the repository structure are under LGPL. If you contribute a filter, you are submitting it to a repository with that license. The maintenance cost is ongoing. The acceptance policy requires regular updates, at least 10 per month. If you stop updating, the filter is removed after a year. The repository also has a deprecated flag to mark filters that are no longer relevant, but they are still built. This means the registry carries dead weight unless the product decides to hide or disable it. For a filter author, this is a long-term commitment, not a one-time submission.

Editorial conclusion

Adopt this repository if you maintain a filter list and want it distributed to AdGuard users, or if you need to understand how AdGuard transforms filter lists. Do not adopt it if you expect a general-purpose ad blocker or a tool for creating filters from scratch. Before contributing, verify your filter meets the acceptance policy: at least 50 GitHub stars, 10 updates per month, and a public discussion channel. Check the trust level assigned to your filter, because low or high trust may disable some of your rules. For a specific next step, read the compiler documentation linked from the README to see how trust levels affect rule types.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases