adblock-lists

What the repository collects

Brave uses the community-maintained EasyList, EasyPrivacy, and uBlock Origin filter lists by default to block ads and trackers, and this repository collects additional filter lists beyond those upstream lists. You can see which filter lists are enabled by default in the list catalog maintained in the brave-adblock-resources repo. Over time the repository has grown to collect all privacy-related lists, not just adblock filter lists. The backend logic for downloading and shipping these lists out to clients lives in a separate packager repo, and adding a new list here also needs changes there. The project points readers to a wiki guide on shipping a file to all clients for the full process. This structure keeps the filter definitions separate from the delivery machinery, so list authors can focus on rules while the packager handles packaging and distribution. For someone curious about how a browser stays current with the filter ecosystem, this repo is the place where Brave-specific additions live, layered on top of the widely used community lists that most blocking tools share. The separation also means a rule author can iterate on text without touching the release pipeline that turns lists into browser components. The catalog in brave-adblock-resources is the single place that defines what is active, so this repo is one input into that catalog rather than the whole picture of blocking.

How a new list ships

Adding a list follows two paths depending on what the list is for. If you are adding a non-adblock list, it usually belongs in a new CRX component, because lists added here must be fetched and packaged by the packager to reach Brave browser clients. The browser also needs to know to download and register the new component, which the ship-a-file guide covers. If the new list is for an existing component, you can skip component generation and instead add download support in the packager, though the README notes this is not usually recommended and most new lists need their own dedicated component. For an adblock filter list meant for consumption by the Rust engine in brave-core, the packager loads lists from the adblock-resources list catalog, which holds every active filter list on Brave. You first get a raw file link such as the brave-lists path on raw.githubusercontent.com, then add that source to a component in the catalog using the raw link as the url. Adding a new component follows the adblock-resources guide for creating and registering it on client machines, so the new rules actually reach users through the normal update channel. Most new lists get their own component because sharing an existing one risks interfering with rules that other consumers depend on in the browser at update time.

Testing and contribution scope

The repository documents how to test changes to two specific lists before they ship. If you modify the debounce.json or clean-urls.json lists, you follow instructions in the Brave browser wiki for testing new rules locally, so debouncing and URL cleaning behave as intended before a release. The scope of contributions here is narrow by design. This is not a place to write a new blocking engine. It is a curated collection of filter list text and the metadata needed to ship it. Contributors who want a list to reach users must understand both the rule format and the packaging side, because a list added here does nothing until the packager and the component registration pick it up. The README keeps its guidance practical, pointing to the packager repo and the adblock-resources repo for the parts it does not own. For a downstream user the takeaway is simple. The lists in this repo are the extra layer Brave applies on top of EasyList, EasyPrivacy, and uBlock Origin, and each one enters the browser through the same catalog-driven pipeline, with the catalog as the single source of truth for what is active. The debounce and clean-urls lists have their own local test steps because their rules affect how URLs are rewritten before a page loads in the browser.

Editorial conclusion

The repository is written in the Adblock Filter List format, distributed under the MPL-2.0 license, and was last updated on 2026-08-24.