Static filter syntax

uBlock Origin (uBO) supports most of the EasyList filter syntax. You can refer to existing filter syntax documentation from Adblock Plus (ABP) and AdGuard (AG).

While uBO does not support some specific cases, it further extends the EasyList filter syntax, which also may share with AG's extended syntax. Here are the most surprising cases documented.

Starting with 1.46.1b15, you can use regex-based values as target domain for static extended filters, see more here.

• Not supported
• Pre-parsing directives
• Extended syntax
  • Static network filtering
    • HOSTS files
    • Modifier filters
    • Narrowing options for network filters ↪
  • Static extended filtering
    • Entity
    • Hostname regex
    • Specific-generic
    • Cosmetic filters
      • Procedural cosmetic filters ↪
    • Action operators
    • HTML filters
    • Response header filtering
    • Scriptlet injection
      • Resources library ↪

It is not supported. The document option used with an exception filter is to disable uBO. The document option in static exception filters is 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 Trusted sites feature), not having some external filter list decide for them.

Note: it still works to negate strict blocking when explicitly enabled by blocking filter document option.

It is not supported.

This option gets 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 a filter option would cause large numbers of filters to be silently disabled for a site where applied.

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.

Supported starting with uBO 1.23.0, also aliased as ehide.

Before 1.23.0 it was translated internally to generichide. elemhide was only available as "No cosmetic filtering" switch.

Keep in mind that generichide is a cosmetic filtering-related option, and using it has no negative consequence concerning privacy since cosmetic filtering has no privacy value.

uBO 1.16.0 and above supports pre-parsing directives. Pre-parsing directives prefixed with !# means older versions of uBO or other blockers will see the pre-parsing directives as a comment and discard them.

The pre-parsing directives execute before a list's content is parsed and influence the final content of a filter list.

The !#include directive allows importing another filter list in place of where the directive appears. The purpose is to allow filter list maintainers to create filters 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. It is not allowed to load a sub-list located outside where the current one resides.

Correct usage:

• !#include ublock-filters.txt
• !#include ublock/filters.txt

Incorrect usage:

• !#include https://github.com/uBlockOrigin/uAssets/blob/master/filters/filters.txt
• !#include ../filters.txt

Related discussion and live example of usefulness:

• https://github.com/yourduskquibbles/webannoyances/issues/67

The !#if directive allows filter list maintainers to create areas in a filter list that get parsed only if certain conditions are met (or not met). For example, use this to create filters specific to a particular browser.

For example, to compile a block of filters only if uBO is running as a Firefox add-on:

!#if env_firefox
...
!#endif

Another example is to compile a block of filters only if uBO is not running as a Firefox add-on (you can negate using !):

!#if !env_firefox
...
!#endif

Conditions can be combined using &&. For example, compile in all versions of uBO except on mobile devices.

!#if (ext_ublock && !env_mobile)
...
!#endif

Support for preprocessor directives is the result of discussion with AG developers. See https://github.com/AdguardTeam/AdguardBrowserExtension/issues/917.

After 1.50.1b9, uBO is fully compatible with the !#if directives found throughout AdGuard's filter lists.

uBO supports only the following, and anything else gets ignored:

Starting from 1.22.0, you can use the !#if false directive to disable a large block of your filters without having to remove them.

!#if false
...
!#endif

Before this version, you could use negated ext_ublock since this token always equals true in uBO.

Starting from 1.50.1b9, you can use the !#else directive:

!#if cap_html_filtering
example.com##^script:has-text(fakeAd)
!#else
example.com##+js(rmnt, script, fakeAd)
!#endif

uBO extends ABP filter syntax.

• _ (aka "noop")
• * (aka "all URLs")
• $1p ($first-party)
• $3p ($third-party)
• $all (all network-based types + $popup + $document + $inline-font + $inline-script)
• $badfilter
• $css ($stylesheet)
• $cname
• $denyallow
• $document
• $domain ($from)
• $elemhide ($ehide)
• $font
• $frame ($subdocument)
• $genericblock Not supported
• $generichide ($ghide)
• $header
• $image
• $important
• $inline-script
• $inline-font
• $ipaddress
• $match-case
• $media
• $method
• $object
• $other
• $permissions
• $ping
• $popunder
• $popup
• $script
• $specifichide ($shide)
• $strict1p
• $strict3p
• $to
• $top
• $webrtc example.com##+js(nowebrtc)
• $websocket
• $xhr ($xmlhttprequest)
• $csp
• $empty ($redirect=empty)
• $mp4 ($redirect=noopmp4-1s)
• $redirect
• $redirect-rule
• $removeparam
• $replace (only from a trusted-source origin)
• $uritransform (only from a trusted-source origin)
• $urlskip (only from a trusted-source origin)

uBO can also parse HOSTS file-like resources. All hostname entries from a HOSTS file resource from uBO's point of view will be syntactically equivalent to a filter using the form ||hostname^.

However, this creates an ambiguity with the ABP filter syntax, which is pattern-based. For example, consider the following filter entry:

example.com

ABP filter syntax dictates that this gets interpreted as "block network requests whose URL contains example.com at any position".

However, in uBO, the interpretation will be "block network requests to the site example.com and all of its subdomains", which is the equivalent to ||example.com^. Note that this includes blocking the main document itself, see "Strict blocking" and document option.

So in uBO, any pattern that reads as a valid hostname will be assumed to be equivalent to a filter of the form ||example.com^. If ever you want such a filter syntactically parsed according to ABP's interpretation, add a wildcard at the end:

example.com*

If the filter is a filename, it is best to prepend with a slash to ensure it's not parsed as a hostname:

/example.js

Related:

• Hosts files in uBO: Block more, way more
• Hosts files at OS level vs hosts files in uBO

Just a placeholder.

Implemented to resolve ambiguity in $removeparam filters with Regular Expression parameters detected as plain Regular Expression filters because of leading and trailing slashes:

/ad-$removeparam=/^foo=bar\d$/,_

Starting from 1.50.1b11, you can use the _ option to also resolve readability issues by supporting multiple instances of the _ option in a single filter:

||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party

The wildcard character * gets used to apply a filter to all URLs. Not recommended 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 at example.com.

Usually, it is far more convenient to use dynamic filtering rules instead of generic static filters.

Equivalent to first-party uBO option, which in turn is negated third-party option (~third-party).

Filter will match on requests to currently visited domain.

Equivalent to third-party option.

Filter will match on requests to other than currently visited domain.

New in 1.20.0.

The all option is equivalent to specifying all network-based types + popup, document, inline-font and inline-script.

Example:

||bet365.com^$all

Above will block all network requests, block all popups and prevent inline fonts/scripts from bet365.com. The EasyList-compatible syntax does not allow this when using only ||bet365.com^.

Used to disable an existing filter. Occasionally disabling a blocking filter is better than creating an exception filter. Just for example's sake, let's say that a mind-absent filter list maintainer added the following filter to their list:

*$image

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 that should get blocked legitimately to no longer be blocked. In such case, the badfilter option is best:

*$image,badfilter

It will cause the *$image filter to get discarded. Appending the badfilter option to any instance of static network filter will prevent the loading of that filter.

After 1.19.0, any filter which fulfills ALL the following conditions:

• Is of the form |https:// or |http:// or *; and
• Does have a domain= option; and
• Does not have a negated domain in its domain= option; and
• Does not have csp option; and
• Does not have a redirect= option

Will process in a certain way:

• The domain= option will be decomposed to create as many distinct filters as there are values in the domain= option.
• It now becomes possible to badfilter only one of the distinct filters without having to badfilter them all.
• The logger will always report these special filters with only a single hostname in the domain= option.

Equivalent to stylesheet option. For convenience.

^{Framework compatibility: Firefox MV2-only}

New in 1.26.0.

When used in an exception filter, it will bypass blocking CNAME uncloaked requests for the current (specified) document.

Network requests resulting from resolving a canonical name are subject to filtering. Creating exception filters using the cname option can bypass this filtering.

Example:

@@*$cname

The filter above tells the network filtering engine to accept network requests which fulfill all the following conditions:

• network request is blocked
• network request is that of an unaliased hostname

Filter list authors are discouraged from using exception filters of the cname type unless there is no other practical solution such that the maintenance burden becomes the more significant issue. These exception filters should be as narrow as possible. For example, they apply to a specific domain, etc.

New in 1.26.0.

The purpose of denyallow is to bring default-deny/allow-exceptionally ability into the static network filtering arsenal.

Example:

*$3p,script,denyallow=x.com|y.com,domain=a.com|b.com

The above filter tells the network filtering engine when the context is a.com or b.com; it needs to block all 3rd-party scripts except those from x.com and y.com.

Note that the domain= option is required!

Essentially, the new denyallow option makes it easier to implement default-deny/allow-exceptionally in static filter lists. It had to be done before with unwieldy regular expressions[1] or through the mix of broadly blocking and exception filters[2].

"Entity" wildcard matching is not supported.

[1] https://hg.adblockplus.org/ruadlist/rev/f362910bc9a0

[2] Typically filters whose patterns are of the form |http*://

See also: to

Alias: doc

It is a type option (like image or script) that specifies the main frame (a.k.a. the root document) of a web page. This option is automatically enabled in filters indicating only the host part of the URL (see "HOSTS files" section), causing web pages that match the filter to get subjected to "Strict blocking".

See also: all

Alias: from

Restrict the filter to be applied only on the specified domain(s).

Use the | symbol to join multiple domains.

Preceding the domain name by ~ will prevent the filter from being applied on this domain.

Starting with 1.28.0 support for "entity" matching has been added. You can now use filter$domain=google.* to apply a filter to pages on all top-level domains of the specified domain.

Example:

||doubleclick.net^$script,domain=auto-motor-und-sport.de
||adnxs.com^$domain=bz-berlin.de|metal-hammer.de|musikexpress.de|rollingstone.de|stylebook.de
/adsign.$domain=~adsign.no

Starting with 1.46.1b17 support for regex-based values has been added. Example of usage: @@*$ghide,domain=/img[a-z]{3,5}\.buzz/

Related discussion: uBlockOrigin/uBlock-issues#2234

Regex-based domain values can be negated just like plain or entity-based values: *$domain=~/regex.../

See also: ipaddress and to.

Alias: ehide

Before uBO 1.23.0, this was being translated internally to generichide.

When used in an exception filter, this will turn off all cosmetic filtering on matching pages.

Equivalent to ~third-party option. Provided strictly for convenience (0.9.9.0).

Equivalent to subdocument option. For convenience.

New in 1.46.1b0.

It is just an alias for the domain= option. The logger will render domain= network filters using the from= version.

See: domain