Skip to content

Frequently asked questions (FAQ)

Jump to bottom
Raymond Hill edited this page Dec 14, 2024 · 73 revisions

Back to Wiki home

Frequently asked questions (FAQ)

uBO = uBlock Origin. uBOL = uBlock Origin Lite.

Will uBO automatically transition to uBO Lite in the Chrome Web Store?

No.

You will have to find an alternative to uBO before Google Chrome disables it for good.

I consider uBO Lite to be too different from uBO to be an automatic replacement. You will have to explicitly find a replacement to uBO according to what you expect from a content blocker. uBO Lite may or may not fulfill your expectations.

See latest Google Chrome announcement regarding the phasing out of MV2 extensions.

If I install uBOL, will I see a difference with uBO?

Maybe. Maybe not. It depends on:

  • Websites you visit
  • How you configured uBO
  • How you configured uBOL

In short, only you can tell.

It's very possible that the sites you visit do not require any of the filtering capabilities specific to uBO, in which case you won't see a difference.

Also, mind that by default there is no cosmetic filtering or scriptlet injection in uBOL (webextensions #362), while these occur by default in uBO. In uBOL, you will have to raise the blocking mode to either Optimal or Complete to benefit from cosmetic filtering and scriptlet injection.

Furthermore, uBOL requires the default mode to be Optimal or Complete for some advanced filtering capabilities to take effect, while they are enabled by default in uBO (see Filtering capabilities which can't be enforced without broad read/modify permissions).

In general, uBOL will be less effective at dealing with websites using anti-content blocker or minimizing website breakage because many filters can't be converted into DNR rules (see log of conversion for technical details).

Note that at time of writing, Firefox's DNR implementation does not yet support the domainType property (bugzilla 1797408), which may cause website breakage (example). Fixed in Firefox 128.

Is uBOL more efficient CPU- and memory-wise than uBO?

In truth, only benchmarks with proper methodology can really answer that question, otherwise it's all speculations. Given the difference between MV2 and MV3 extensions, a proper methodology would require to measure overall CPU and memory usage when loading actual webpages from real websites when both extensions are configured to act in a similar way.

At the moment, Firefox's implementation of declarativeNetRequest API is JavaScript-based and does not appear to be particularly optimized (see bugzilla 1745768). Chromium's implementation is C++-based.

Keep in mind that uBO's own JavaScript-based network filtering engine has been measured to be faster than a well-known Rust-based filtering engine (though the measured difference back then was low single-digit µs, not something that will ever be perceivable by a end user).

Addendum: A recent DebugBear benchmark started to shed a bit of light on performance comparison between MV2- and MV3-based content blockers, see https://x.com/gorhill/status/1792648742752981086.

Filtering capabilities which can't be ported to MV3

Because the declarativeNetRequest API does not support the ability to enforce rules according to the top context, i.e. the URL in the address bar, the following capabilities can't be supported:

The declarativeNetRequest API does not allow to filter according to the content of response headers, thus not possible:

The following filter options can't be translated into DNR rules:

  • strict1p, strict3p: whether a network request is same-origin as its initiator
  • Entity-based values for domain= filter option (webextensions #394)
  • redirect-rule=: the DNR API does not support redirect-if-blocked concept (webextensions #493)
  • Regex-based removeparam= modifier filter options
  • Exceptions for all modifier filter options are not possible
  • Many very useful regex-based filters used in uBO are not allowed, or are rejected by the DNR API (webextensions #344)
  • replace=, can't modify the response body (full support is only possible with Firefox MV2)
  • ipaddress=, can't use IP address as a condition to block/unblock (full support is only possible with Firefox MV2)
  • urlskip=, this requires programmatic steps to extract a URL from another URL (partial support, for strict-blocked pages only)

CNAME-uncloaking is up to each DNR implementation; no DNR implementation supports this capability at the time of writing.

Filtering capabilities which can't be enforced without broad read/modify permissions

The following modifier filter options can't be enforced without broad read/modify permissions, i.e. when default mode is Basic: redirect=, removeparam=, csp= (webextensions #169), permissions=. They will be enforced when default mode is either Optimal or Complete.

For instance, this explains why the rule count of AdGuard URL Tracking Protection is zero in Basic mode, since the whole ruleset consists of removeparam= filters.

When do filter lists update?

When the extension updates to a new version (webextensions #112).

There are no filter lists proper in uBOL. There are declarative rulesets and scripts which are the results of compiling filter lists when the extension package is generated. Those declarative rulesets and scripts are updated only when the extension itself updates. As a result, uBOL never makes network requests to any remote servers.

More technical details

Injecting content scripts in a non-declarative way is unreliable in MV3 due to fact that extensions are really service workers which can be suspended at any time. By the time a service worker wakes up and proceed to inject the required content scripts through scripting.executeScript API, these content scripts might be unable to accomplish their duty when the webpage has already started loading.

For an extension to be entirely declarative, it must package all the scripts to inject anywhere, the scripting.registerContentScript API doesn't allow injecting code as string, the content scripts must be part of the package.

The userScripts API does allow to inject code as string, but it's impractical as in Chromium-based browsers this requires extra steps by the user to enable the API. In Firefox, the documentation for this API has the following note:

When using Manifest V3 or higher, use scripting.registerContentScripts() to register scripts

Is the limit on maximum number of DNR rules an issue?

Not really at this point. Special attention has been given to generate the smallest amount of rules when compiling filter lists into rulesets at extension build time.

The current limit imposed by the various implementations is 30K.

The default ruleset in uBOL hovers around 17K when using Optimal or Complete mode (less in Basic mode).

When also enabling all five Annoyances rulesets, three Miscellaneous rulesets, and one large regional ruleset, the total number of DNR rules is still under 30K. At that point the issue becomes more the limit on the maximum number of enabled rulesets, which is currently 10 at the time of writing (webextensions #318).

What are the upsides of an MV3-based content blocker?

For Chromium-based browsers specifically, MV3-based content blockers which are entirely declarative will properly filter at browser launch, which is not the case for MV2-based content blockers. Not all MV3-based content blockers are entirely declarative, so these may still suffer filtering reliability issues at browser launch.

Note though that this is not an issue for Firefox MV2-based uBO, see uBlock Origin works best on Firefox / Browser launch.

Is uBO Lite a bad faith attempt at converting uBO to MV3?

See https://news.ycombinator.com/item?id=40533085

No.

My goal with uBO Lite is a reliable and efficient MV3-compliant content blocker, leveraging the filter lists used by uBO. I am satisfied that I fulfilled that goal by ensuring uBO Lite was entirely declarative -- though at the cost of limitations beyond those intrinsic to MV3.

Reliability: Being entirely declarative, uBO Lite's service worker is not required to initiate network-, cosmetic-, or scriptlet-based filtering in a timely manner.

As a result, uBO Lite reliably filters at browser launch, or when navigating to new webpages while its service worker is suspended. This can't be achieved without uBO Lite's declarative approach. Example:

ABP 4.1 (MV3-compliant): fails to filter properly at browser launch
abp.mp4
uBO Lite 2024.5.29.835: filters properly at browser launch
ubo.mp4

Efficiency: uBO Lite being entirely declarative means its service worker is lightweight and initialize optimally when activated.

Non-declarative MV3-based content blockers will suffer unreliable filtering when their service worker has been suspended, since waking up a service worker requires a lot of initialization work and delays time-critical filtering abilities. Such content blocker may end up using trickery to force their service worker to always be up and running.

For instance, ABP 4.1 uses such trick to keep its service worker alive and ready to act: the service worker is force-restarted each time it is terminated by the browser, so every 30 seconds when the browser is idle. Despite using this trick, there is still no guarantee reliable filtering will occur should timely filtering be required just as when the service worker is being woken up (all event handlers are non-blocking in MV3).

Task manager: ABP 4.1 vs. uBO Lite 2024.5.29.835

This is a capture of Chromium's task manager at browser launch.

  • uBOL: Service Worker: chrome-extension://jifpbecc... entry
  • ABP: Service Worker: chrome-extension://cfhdojbk... entry. Notice the peaks in CPU and memory usage every 30 seconds.
a-2024-06-02_10.50.36.mp4

The choice of being entirely declarative for the sake of reliability and efficiency meant sacrificing being able to import filter lists or create custom filters, hence the "Lite" in uBO Lite: it's not meant as an MV3-compliant version of uBO, it's meant as a reliable Lite version of uBO, suitable for those who used uBO in an install-and-forget manner.

Can I use other content blocker(s) along uBO Lite?

No, for the same reasons that you should not use another content blocker with uBO. See https://x.com/gorhill/status/1033706103782170625.

Also as with uBO, other non-content blocking extensions can also interfere. If you suffer filter issues with uBO Lite, first select a different blocking mode.

If the issue still exists regardless of the blocking mode, try disabling all other extensions first to see if the issue persists (be sure to open the website with the issue in a new tab once you have disabled all other extensions).

Is the development of uBO Lite frozen?

No.

However I will be extremely careful to...

  • ... not add features which may end up undermining the current upsides of uBO Lite, like the benefits of its fully declarative approach
  • ... not add maintenance burden which could put the project at risk of being dropped (as happened with uMatrix)
Clone this wiki locally