Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Static filter syntax
uBlock Origin ("uBO") supports Adblock Plus ("ABP") filter syntax, so you can refer to existing filter syntax documentation from Adblock Plus web site and ABP's filter cheatsheet.
However uBO does not support some very specific cases, and also adds its own extensions to ABP filter syntax (which at time of writing are not recognized by ABP).
- Not supported
- Pre-parsing directives
- Extended syntax
document for exception filters (those prefixed with
Not supported. The purpose of the
document option when used with an exception filter is to disable uBO completely. The purpose of the
document option in static exception filters is mostly for the sake of "acceptable ads" support, which uBO does not support.
The reason it is not supported is to be sure that users explicitly disable uBO themselves if they wish (through whitelisting), not having some external filter list decide for them.
This option is meant to be used with an exception filter to disable generic network filters on target pages. Generic in this case means network filters without a
domain= filter option. Filters such as
||example.com^ are still considered generic.
This option is not supported because using such filter option would cause large amount of filters to be silently disabled for a site where it's used.
For instance, when used for a specific site, the
genericblock option would cause all the filters in hosts files to be disabled, including those from the malware lists. EasyPrivacy and other anti-tracking lists also contain countless so-called "generic" filters, and as a consequence these would also end up being disabled.
Translated internally to
elemhide is used with exception filters to disable all cosmetic filtering on page, this can be achieved by "No cosmetic filtering" switch.
Keep in mind
generichide is a cosmetic filtering-related option, and as such using it has no negative consequence with regard to privacy since cosmetic filtering has no privacy value.
uBO v1.16.0 and above supports pre-parsing directives. Pre-parsing directives are prefixed with
!#, so this means older versions of uBO or other blockers will see the pre-parsing directives as comment and discard them.
The pre-parsing directives are executed before a list content is parsed, and influence the final content of a filter list.
!#include [file name]
!#include directive allows to import another filter list in place where the directive appears. The purpose is to allow filter list maintainers to create filters which are specific to uBO, while keeping their list compatible with other blockers. Other blockers will ignore the
!#include directive, because it will be seen as a comment and thus discarded. uBO will attempt to load the resource found at
[file name] (the sub-list) and load its content into the current list.
The sub-list must be in the same directory as the main one, i.e. it is not allowed to load a sub-list which is located outside where the current one resides.
!#if directive allows filter list maintainers to create areas in a filter list which will be parsed only if certain conditions are met (or not met). For example this can be used to create filters which are specific to a particular browser.
Example, to compile a block of filters only if uBO is being run as a Firefox extension:
!#if env_firefox ... !#endif
Another example, compile a block of filters only if uBO is not being run as a Firefox extension:
!#if !env_firefox ... !#endif
Support for pre-processor directives are the result of discussion with AdGuard developers, see https://github.com/AdguardTeam/AdguardBrowserExtension/issues/917.
For the time being, only a single token is supported in a
!#if directive (can be negated using
!), and uBO supports only the following tokens, anything else will be ignored:
ext_ublock env_chromium env_edge env_firefox env_mobile env_safari cap_html_filtering cap_user_stylesheet
ext_ublock is always true in uBO, you can use a
!#if directive to disable a large block of your filters without having to remove them:
!#if !ext_ublock ... !#endif
uBO extends Adblock Plus filter syntax.
Static network filtering
uBO can also parse HOSTS file-like resources. However, this creates an ambiguity with ABP filter syntax, which is pattern-based. For exemple, consider the following filter entry:
ABP filter syntax dictates that this is interpreted as "block network requests which URL contains
example.com at any position". However if the entry comes from a HOSTS file, the interpretation must be "block network requests to the site
So in uBO, any entry which can be read as a valid hostname, will be assumed to be a HOSTS file entry. If ever you want such filter to be parsed as an ABP filter, just add a wildcard at the end:
* aka "all URLs"
The wildcard character
* can be used to apply a filter to all URLs. This is not recommended though, unless you further narrow the filter using filter options. Examples:
*$third-party: block all 3rd-party network requests.
*$script,domain=example.com: block all network requests to fetch script resources from
Usually, it is far more convenient to use dynamic filtering rules in lieu of such generic static filters.
To disable an existing filter. Sometimes, disabling an existing blocking filter is better than creating an exception filter. Just for example sake, let's say that a mind-absent filter list maintainer added the following filter in his list:
Now all images from everywhere are blocked on your side. An exception filter (
@@*$image) is not a good solution because it would also cause images which should be legitimately blocked from no longer being blocked. In such case, the
badfilter option is best:
This will cause the
*$image filter to be discarded. Just appending
,badfilter to any instance of static network filter will prevent the loading of that filter.
For block filters only. This is type option (like
script) which specifies main frame (a.k.a. the root document) of a web page. Usually not necessary, because uBO implies it for filters specifying only host part of the URL. This will cause web pages which match the filter to be subjected to strict blocking.
This is equivalent to
~third-party. Provided strictly for convenience (0.9.9.0).
The filter option
important means to ignore all exception filters (those prefixed with
It applies only to network block filters. The
important option will allow you to block with 100% certainty specific network requests.
||google-analytics.com^$important,third-party will block all network requests to
google-analytics.com, disregarding any existing network exception filters. Another example:
To specifically disable inline script tags in a main page:
To block "popunders" windows/tabs. To be used in the same manner as the
popup filter option, except that it will block popunders.
To cause a blocked network request to be redirected to a local "neutered" version of the resource. The "neutered" resource must be referenced using a resource token. The resources are defined in uAssets/filters/resources.txt.
The filter syntax for
redirect= filter option is a subset of ABP-compatible filtering syntax, and is as follow:
||example.com^$script,redirect=noopjs,domain=github.com ||example.com/path/to/image$image,redirect=2x2-transparent.png,domain=github.com ||example.com/$script,redirect=noopjs,first-party
Specifically, notice that the filter must start with
*, otherwise no redirection directive will be created, although a blocking filter will be created. Essentially, a redirection filter must always have a destination hostname specified, or
* if the filter is to apply to all destinations*.
A source hostname should always be specified, so the
domain= option is strongly recommended. It is allowed to use
first-party instead of
domain=[...], in which case the source hostname will be that of the destination hostname.
* redirections applied to all destinations (starting with
*) cannot be narrowed by
~third-party option #3590
Static extended filtering
Static extended filters are all of the form:
The most common type of static extended filters are cosmetic filters, also known as "element hiding filters" in Adblock Plus.
All static extended filters can be declared to apply to a specific entity. For example:
An entity is defined as follow: a formal domain name with the Public Suffix part replaced by a wildcard.
google.* will apply to all similar Google domain names:
google.co.uk, etc. Another example:
facebook.* will apply to all similar Facebook domain names:
Since the base domain name is used to derive the name of the "entity",
google.evil.biz would not match
Procedural cosmetic filters
Related issue: Support cosmetic filters with explicit style properties.
By default, the implicit purpose of cosmetic filters is to hide unwanted DOM elements. However sometimes it may be useful to re-style a specific DOM element on a page rather than hide it. Here is an recent example of such cases. This is the purpose of the new
:style-based selector. The syntax is as follow:
example.com##h1:style(background-color: blue !important)
So mainly it's exactly the same syntax of plain cosmetic filters (i.e. must be a valid CSS selector), except that the
:style(...) suffix is appended at the end. The content in the parentheses must be one or more CSS property declarations (separated by the standard
;). It is not allowed to use property values with
style:-based cosmetic filters will be discarded.
As with the other new cosmetic filtering selectors, the
:style can be used only for specific cosmetic filters, i.e. there must be a hostname or entity specified for the filter.
AdGuard already support such feature, although using a different syntax. However uBO is able to transparently convert and make use of the AdGuard's "CSS injection rules" if ever you use an AdGuard filter list in uBO (well, this essentially means you can use AdGuard's syntax in uBO if you prefer).
For example, AdGuard English filter contains ~50 styling filters, AdGuard Russian filter list contains ~250 styling filters, etc. Note that often styling filters are used to foil anti-blocker mechanism on web pages. Given this, you may want to benefit from AdGuard's filter lists, which can be enabled from the 3rd-party filters pane.
Supported by uBO 1.14.23b3+ in Firefox 57+.
READ VERY CAREFULLY: HTML filtering acts on the response data (before browser parsing). Do not use the browser inspector from developer tools to create HTML filters. You must use
view-source:[URL of page] instead to look at the response data and find out relevant information to create relevant HTML filters.
The purpose of HTML filters is to remove elements from a document before it is parsed by the browser.
The syntax is similar to that of cosmetic filters, except that you must prefix your selector (CSS or procedural) with the character
These HTML filters will cause the elements matching the selectors to be removed from the streamed response data, such that the browser will never know of their existence once it parses the modified response data. This makes it a powerful tool in uBO's arsenal.
With the introduction of HTML filtering, the
script:contains(...) is now deprecated and internally converted into an equivalent
##^script:has-text(...) HTML filter. The result is essentially the same: to prevent the execution of specific inline script tags in a main HTML document. See "Inline script tag filtering" for further documentation.
Starting from 1.15.12 uBO supports new shorter syntax:
script:inject filters are ignored: those filters must be specific, i.e. they must apply to specific hostnames, e.g.