uBlockOrigin/uAssets: the filter list repository behind uBlock Origin, and when to file an issue there

What uAssets actually is, and who files reports there

uAssets is the repository for the resources of uBlock Origin. According to the README, it receives all reports for new filters or for existing filters that cause web page breakage. That single sentence defines both its scope and its audience: people who use uBO or uBO Lite and hit a page that breaks, plus contributors who write or repair the filter rules themselves. It is not a package you install, and it is not a distribution channel for the extension. The repository's primary language is listed as Adblock Filter List, which is a fair description of what the bulk of the tree contains.

The README also states the bar for a filter to be included: any filter added to uBO's filter lists must use the extended syntax, the uBO-specific static filter syntax documented in the project wiki. The rationale for accepting a given filter follows the EasyList and EasyPrivacy policies, with the additional question of whether the filter needs that extended syntax at all. That second condition is the interesting one. A plain network rule that EasyList would accept does not obviously belong here, and the README says it is preferred to fix filter issues in EasyList. Contributors who prove valuable are given write permissions, so the trust model is reputation-based rather than a formal review board.

The exception list: what uAssets will fix even without extended syntax

The README carves out a set of problems that uAssets will address even when a fix does not require the extended syntax. The list is short and worth reading literally: ad-reinsertion, anti-blocker, context menu blockage, cut/copy/paste blockage, popups and popunders, website breakage, and video ads. These are categories where the failure is either a direct circumvention of the blocker or a visible loss of function on the page, so the maintainers treat them as in scope regardless of which syntax the fix needs.

The exclusions are just as specific. uAssets will not address paywalls, porn farms, or annoyances such as widgets, social media buttons, newsletter subscriptions and donation requests. That is a policy choice, not a technical limit, and it means a report about a cookie banner or a floating share bar is likely to be closed even if a one-line filter would work. The README adds that new filter list requests in the issue tracker are not permitted and will be declined and closed, which rules out the common request to add a third-party list to the defaults.

There is also a coordination rule that catches people out. The README warns, in bold, not to use any other similarly-purposed blockers concurrently with uBO, because it can result in website breakage or undefined results. If you file a breakage report while a second blocker is enabled, you may be reporting an interaction that uBO cannot reproduce.

How the filter tree and validation tooling are laid out

The top level of the repository contains .github/, dnr/, filters/, templates/, thirdparties/, tools/, a Makefile, CONTRIBUTING.md and LICENSE. The filters/ directory is where the filter lists themselves live, and the Makefile shows the naming pattern: filters/filters.txt, filters/filters-2020.txt, filters/filters-2021.txt and so on through filters-2025.txt and filters-2026.txt, plus separate targets for privacy, annoyances and badware validation, and a ubol-filters target. The dnr/ directory sits alongside them, which is consistent with the README's references to the Manifest Version 3 variant, uBO Lite, whose declarativeNetRequest rules are a different mechanism from classic static filters.

The validation pipeline is visible in the Makefile. It copies tools/validate/ into build/validate/, runs tools/make-validate.sh to produce a build/validate/uBlock directory, and then invokes node build/validate/validate.js with an in= argument naming a filter list and an out= argument pointing at build/validate/results. Each list gets its own target, so filters.results.txt, filters-2020.results.txt and the rest are produced by the same script with a different input. In other words, the repository validates its own lists against a build of uBO rather than trusting a linter alone. The Makefile excerpt is truncated in the repository, so the full set of targets beyond the year-based ones and the ubol-filters target cannot be confirmed from what is available.

Reporting a breakage: the exact steps for uBO and uBO Lite

The README gives a concrete procedure, and it starts with a control step: disable all other browser extensions and check whether the issue still occurs. Only if it does should you collect troubleshooting information. For uBO, the steps are to open a new browser tab, go to the page where the issue occurs, click the uBO icon, click the chat icon, click Troubleshooting Information, click Select all and copy, then paste the contents into the appropriate GitHub thread. For uBO Lite the path differs slightly: open a new tab, go to the page, click the uBO Lite icon, choose the Report an issue menu item, click Troubleshooting Information, copy the contents, and paste them into the thread.

There is no command line involved, and the repository does not document an installation step for the filter lists because they ship with the extension. What a contributor can run locally is the validation tooling, and the Makefile shows the shape of it. The relevant variables are the input list path and the output directory:

make validate-filters

That target is declared in the Makefile's .PHONY list along with validate-filters-2020 through validate-filters-2026, validate-privacy, validate-annoyances, validate-badware and validate-ubol-filters. Running it drives the node build/validate/validate.js invocation shown in the Makefile, which reads filters/filters.txt and writes results under build/validate/results. What you should expect to see is a results file named after the input list, for example filters.results.txt, in that output directory.

If you only want the validation script copied into place without running a full list, the Makefile separates those steps:

cp -R tools/validate/* build/validate/
tools/make-validate.sh

The first command mirrors the tools/validate/ contents into build/validate/, matching the Makefile's own rule for build/validate/validate.js. The second builds the uBlock directory the validator expects, which is the build/validate/uBlock prerequisite listed for every results target. The README does not document a rollback procedure for a filter change, so if you are preparing a pull request, check CONTRIBUTING.md in the repository root for the process rather than assuming one.

Where uAssets is the wrong place to ask, and what to use instead

The clearest limit is that uAssets is not a support forum. The README routes support, questions and help to the r/uBlockOrigin subreddit, issues with the extension itself to the uBlock-issues tracker, and issues specific to the Manifest Version 3 variant to the uBOL-home tracker. Filing a general uBO bug in uAssets puts it in the wrong queue, and the README's statement about new filter list requests being declined and closed shows the maintainers do police that boundary.

The second limit is scope by category. Paywalls, porn farms and annoyances are explicitly out of scope, so a reader who wants newsletter popups gone is looking at the wrong project, regardless of how annoying the popup is. Annoyance filtering exists as a concept in the Makefile through the validate-annoyances target, but the README's exclusion list is about what reports uAssets will act on, and the two are not the same thing.

A real alternative in approach is EasyList itself. The README states that it is preferred to fix filter issues in EasyList, and that EasyList-compatible fixes for high-traffic websites are added to uBO filters only until they become added to EasyList. The difference is architectural rather than editorial: EasyList rules must work across many blockers, so they cannot depend on uBO's extended syntax, while uAssets exists precisely for the rules that do. If your problem is a plain network filter that any blocker could apply, EasyList is the upstream home for it, and a uBO-only fix would be a temporary stop. If your problem only a uBO-specific rule can solve, uAssets is the right destination.

Maintenance, licensing and the cost of tracking a moving list

The repository is not archived, and the source gives no last push date, so there is no basis for describing how frequently it changes. What can be said is that the structure implies ongoing upkeep: the Makefile carries per-year filter lists from 2020 through 2026 and a .PHONY target for each, which is a pattern that only makes sense if lists are added and validated year over year. The README's offer of write permissions to proven contributors is another maintenance signal, since it distributes the work of reviewing reports.

For anyone consuming the lists rather than contributing, the upgrade cost is close to zero in the ordinary case, because the lists ship with the extension and update through it. The cost sits on the contributor side: a filter change has to pass the validator for its list, and the Makefile shows that the validator runs against a built uBO, so a local checkout needs node plus the make-validate.sh step before results appear. There are no releases in the repository, so there is no versioned artifact to pin against.

The licence is GPL-3.0, per the repository's LICENSE file. That matters if you intend to reuse filter content in another product rather than just run uBO: GPL-3.0 is a copyleft licence, and the repository README does not offer any additional permission or exception. This is a description of the licence identifier, not legal advice; if you plan to redistribute the lists inside a commercial product, read the licence text and get your own counsel.

Editorial conclusion

Adopt uAssets as a reporting target if you run uBlock Origin or uBlock Origin Lite and can supply troubleshooting information for ad-reinsertion, anti-blocker, context menu blockage, cut/copy/paste blockage, popups, website breakage or video ads. Do not file there for paywalls, porn farms or annoyances, and do not file new filter list requests, since the README says those are declined and closed. Before opening a thread, verify that the problem survives with all other browser extensions disabled, and confirm that the fix cannot land in EasyList instead, because the README prefers EasyList fixes and only keeps EasyList-compatible fixes for high-traffic sites in uBO filters until they are added upstream.

Frequently asked questions

Official sources

1. Official README
2. Project repository