Brave adblock-lists: How Brave Extends Its Default Filter Rules

What adblock-lists is and who it is for

Brave adblock-lists is a developer and contributor repository maintained by Brave Software. It collects the supplementary filter rules that Brave Browser ships on top of the community-maintained EasyList, EasyPrivacy, and uBlock Origin filter sets, which the browser uses by default. The repository is not a standalone ad blocker and does not function independently of the Brave Browser infrastructure.

The README states that the project has evolved beyond its original scope of ad blocking to cover all privacy-related lists. This includes tracking protection rules, debounce rules that strip tracking parameters from redirect URLs, and clean-URL definitions that normalize link formats before the browser follows them.

The primary audience is Brave's own engineering and privacy team, plus external contributors who have identified a tracking vector or a broken site that warrants a new filter rule or list addition. End users of Brave receive the contents of this repository as part of their browser's built-in protection without ever cloning it.

What this repository adds beyond EasyList and uBlock Origin

Brave Browser uses EasyList, EasyPrivacy, and uBlock Origin's uAssets filter lists by default. The README describes these as upstream lists. Adblock-lists provides everything Brave ships that those upstream sources do not cover.

The repository holds several distinct list types. The brave-lists/ directory contains Brave-authored filter lists for ad blocking and tracking protection, including rules for specific social widgets and regional trackers that the upstream lists do not address. The brave-unbreak.txt file collects exception rules that prevent Brave's filters from breaking sites that upstream rules accidentally block.

The debounce.json and clean-urls.json files represent privacy features beyond conventional ad blocking. Debounce rules intercept redirect chains that route through tracking servers before reaching the actual destination URL. Clean-URL rules strip tracking parameters appended to links. Both of these are not filter lists in the traditional AdBlock syntax sense but serve a privacy purpose that the repository has expanded to house.

The custom/ directory holds additional lists, and the .fopconfig file at the root suggests the repository uses the FOP (Format of Filters Online Compiler) tooling for validation, though the README does not document this workflow in detail.

How filter lists reach Brave Browser users

Filter lists in this repository do not ship directly to users. The pipeline involves two other Brave repositories. The README explains that backend logic for downloading and packaging these lists lives in brave-core-crx-packager, and accompanying resources are in adblock-resources.

The adblock-resources repository maintains a list catalog at filter_lists/list_catalog.json that controls which filter lists are active in Brave and which are enabled by default. When a new list is added to adblock-lists, it must also be registered in that catalog before Brave will include it in a CRX component. The CRX component is then packaged by brave-core-crx-packager and distributed to Brave Browser clients as a browser extension update, separate from the main browser binary.

This architecture means that a change to a filter rule in this repository reaches users through three steps: the rule is merged here, the adblock-resources catalog is updated, and the packager produces a new CRX component. The README notes that each list typically lives in its own dedicated CRX component, which allows Brave to update individual list categories without shipping a full browser update.

Contributing a new filter list: the multi-repository process

Adding a new list requires work across multiple repositories, not just a pull request here. The README outlines the process for both adblock filter lists and non-adblock lists.

For an adblock filter list, the contributor adds the raw .txt file to this repository in the brave-lists/ directory. The raw GitHub URL for that file (in the format used for brave-social.txt under brave-lists/) then goes into the adblock-resources list catalog as the list's source URL. For a new dedicated CRX component, the contributor must also register the component in brave-core-crx-packager and update Brave browser clients to know to download the new component.

For a non-adblock list (such as a debounce or clean-URL rule set), the README directs contributors to the guide at brave-core/docs/ship_a_file_to_all_clients.md for the comprehensive steps. The README notes that in most cases a new list belongs in a new CRX component, not added to an existing one.

The package.json at the repository root shows the project is named adblock-lists with a gyp build file flag, suggesting the repository has build integration beyond simple file hosting. The renovate.json file indicates dependency update automation is configured.

Scope limitations and cases where this repository is the wrong resource

The adblock-lists repository is not a user-configurable filter source. Brave users who want to add custom filter lists to their browser use the Brave Shields settings to add external lists; they do not interact with this repository. There is no documented path for pulling these lists into Pi-hole, AdGuard Home, or other DNS-based blockers, because the lists are designed for consumption by Brave's Rust-based adblock engine with its own syntax and semantic extensions.

The README does not document any standalone testing instructions beyond a reference to Brave browser developer documentation for testing debounce.json and clean-urls.json changes. This means the only tested environment for the rules in this repository is Brave Browser itself. Contributors cannot verify new rules against an independent filter-list validator without access to the Brave development tooling.

EasyList's uAssets repository is a comparable project for contributors who want to participate in the broader open-source ad blocking ecosystem rather than specifically Brave. uAssets provides filter rules for uBlock Origin, which runs as an extension across multiple browsers. The difference in approach is scope: adblock-lists ships with Brave as a first-party maintained collection, while uAssets is a community project covering a general-purpose browser extension.

Maintenance cadence and licensing

The last push was on 2026-09-26, two days before this article was written. The repository receives frequent updates, consistent with an active browser privacy team incorporating ongoing tracker and ad vendor changes. There are no GitHub releases, because the repository's output ships through the CRX component pipeline rather than as tagged versions.

The license is Mozilla Public License 2.0 (MPL-2.0). MPL-2.0 is a file-level copyleft license: files taken from this repository and modified must be shared under the same license, but they can be combined with code under other licenses in a larger work. For contributors adding filter rule files, the practical implication is that the .txt filter list files they contribute fall under MPL-2.0 once merged.

The repository is a first-party Brave Software project. Contributions are reviewed by Brave's security and privacy team before merge, which means the review cycle for new filter lists can take longer than a typical open-source pull request.

Editorial conclusion

Brave employees and external contributors who want to add or fix filter rules in the Brave Browser should start here, then follow the multi-repository path through adblock-resources and brave-core-crx-packager to get a new list shipped. End users of Brave Browser receive the output of this repository automatically with browser updates and do not interact with it directly. Developers maintaining self-hosted ad-blocking infrastructure such as Pi-hole or AdGuard Home should not expect to point directly at this repository's raw files as a general-purpose filter source: the lists are designed for Brave's Rust-based adblock engine, and the README does not document compatibility with other tools. The repository received its last push on 2026-09-26.

Frequently asked questions

Official sources

1. Official README
2. Project repository