Skip to content

Dashboard: Filter lists

Raymond Hill edited this page Oct 2, 2024 · 77 revisions


The Filter lists pane is where you subscribe to filter lists that feed into uBlock Origin (uBO)'s static filtering engine.

The picture below shows uBO's default selection of filter lists. You can add more or remove some filter lists already selected by default. (Most other blockers only enable EasyList.)

Hosts files are also supported, by default two Hosts lists are shipped with uBlock: "Peter Lowe’s Ad and tracking server list" (enabled by default) and "Dan Pollock’s hosts file" (disabled by default).

If you remove filter lists, keeping the uBlock filters is strongly recommended due to their optimization for uBO.

The likelihood of page breakage increases with more filter lists added. When this issue occurs, you should report it to the maintainers of the corresponding filter list or create an exception filter to fix it for yourself.

Filter lists pane


uBO discards duplicate filters, so the number of filters used within a filter list depends on how many duplicates were detected. The order in which filter lists get loaded into memory is undefined.

When you hover the cursor over the clock icon of a filter list, a tooltip will display the last updated time. If you click the clock icon, uBO will mark the list as out-of-date. Outdated lists will be automatically updated in the background when you check the Auto update filter lists option. You can force update outdated lists immediately by clicking the Update now button.

Related: Launch and filter lists load performance


Update now

"Update now" button

This button is available only if there is at least one filter list that is out of date. You can force an update of all outdated filter lists.

When a filter list gets updated using a newer version from its remote location, a clock icon will appear next to it. You can force an update of a single filter list by clicking the clock icon. Clicking this icon will reset the last updated timestamp, remove its content from storage, and cause the Update now button to become available.

update by clock icon

Forcing an update of the "uBlock filters" entry will also update additional resources when possible. (On Chromium-based browsers and development builds, the Resources Library used by scriptlet injection gets updated.)


Purge all caches

"Purge all caches" button

Removed in 1.54.1b11.

This will reset the "last update" timestamp for all of the subscribed filter lists. Essentially, this will cause all filter lists to become out of date. This can be used to force an update of all filter lists.

Clicking this button with Shift (version before 1.34 required also Ctrl) pressed will remove all locally cached content of filter lists, which will force uBO to rebuild all of its databases from the beginning.

The discussion should be continued in already existing main discussion threads:

because there already exists a big pile of unnecessarily created duplicates:

hence there is no point in spamming the issue tracker by creating new duplicates over and over, new threads will be labeled as invalid or duplicate and closed.


Auto-update filter lists

If you check this option, uBO will automatically update the currently selected filter lists at regular intervals. This option is checked by default (recommended).

Filter lists are automatically updated according to expiration time defined by:

  • the Diff-Expires directive if list is compatible with differential updates (uBO 1.54.0+) (in "uBlock filters" currently set to around 5 hours),
  • the Expires directive if present in the filter list header,
  • or the updateAfter attribute if found in the list entry in assets.json,
  • or every 5 days by default.

Don't worry if you sometimes notice that some of your lists are marked "⚠️ Out of date" or some of them appear to update every time you open the dashboard. uBO updates filters lists in periodic sessions. In regular browser usage, the first one begins autoUpdateDelayAfterLaunch (105) seconds after uBO (your browser) is started. Lists found to be outdated (for which expiration time passed) are then downloaded in autoUpdateAssetFetchPeriod (15) seconds intervals. After this update session ends, uBO will wait autoUpdatePeriod (1) hour to start updating filters again. Update session will also be triggered by opening the dashboard, that's why you may notice it more often. As you see, there can be periods of time between update sessions, where your lists appear to be outdated, but it's normal update cycle. In irregular browser usage, when your lists expiration time is exceeded more than twice, uBO will trigger "emergency" update, which should give you all your lists updated in below one minute after start.

Note: As for AdGuard filter lists in uBlock Origin: AdGuard uses a different way to encode diff-expires, currently there is no code yet in uBO to deal with AdGuard's differential update approach, hence their filter lists in uBO lack Diff-Expires directive, and have only Diff-Path, which means that differential updates for AdGuard lists work only in AdGuard, while in uBlock Origin they fallback to regular Expires directive, which is set to 5 days currently in their fiter lists, related issue: Filter list with "Diff-Path" but without "Diff-Expires:".


Parse and enforce cosmetic filters

Uncheck this option if you do not want cosmetic filters from various filter lists to be parsed and enforced. This option is mostly of interest for those who want to further reduce uBO's memory and CPU footprint. Cosmetic filtering has no value privacy-wise, its only purpose is to hide elements on a web page that can't be blocked otherwise. An example of this is the ads served with some Google Search results.

Note that if you disable this option, your own custom cosmetic filters in My Filters (if any) will still be enforced.


Ignore generic cosmetic filters

Generic cosmetic filters are those cosmetic filters that are meant to apply on all websites. Though handled efficiently by uBO, generic cosmetic filters may still end up contributing measurable memory and CPU overhead on some web pages, especially the large and long-lived ones. Enabling this option will eliminate the memory and CPU overhead added to web pages as a result of handling generic cosmetic filters, and also lower the memory footprint of uBO itself. This option can be enabled on very low-end devices, but mind that some filter lists (EasyList Cookie for ex.) rely on generic cosmetic filters a lot, so they may pretty much stop working.


Suspend network activity until all filter lists are loaded

This setting suspends network activity until uBO has loaded all filter lists into memory.

In Firefox-based browsers, this setting is enabled by default. Disabling it gives the option to potentially speed up page load at browser launch, at the cost of possibly not properly filtering network requests as per filter lists or rules.

In Chromium-based browsers, this setting is disabled by default, since Chromium-based browsers do not support natively suspending network requests.2 Enabling this setting in Chromium-based browsers may lead to negative side-effects at browser launch.

See uBlock Origin works best on Firefox / Browser launch.

1 New in 1.41.0.
2 This setting will use any mechanism on the platform not supporting network activity suspension to mitigate the improper filtering of network requests at launch. For example, in Chromium-based browsers it's not possible to suspend network activity, in which case this setting will only force a reload of the webpage once uBO is fully loaded, if that still doesn't work, an user can force manually a reload of the webpage.


Search box

New in uBO 1.50.0, useful to quickly and easily find specific filter lists. uBO's built-in search box is more powerful than browser's built-in search box, and has several benefits over it, because was specifically designed for uBO, comparision is available here: https://github.com/uBlockOrigin/uBlock-issues/discussions/3367#discussioncomment-10567527

search_box_1


Stock filter lists

This is a collection of various filter lists, grouped by purpose. To use a specific filter list, just select it through its checkbox. Any change in the selection of filter lists must be committed by using the Apply change button, which will appear if and only if the current selection of filter lists differs from the previous selection of filter lists.

Important

The more filter lists are selected, the higher the likelihood of websites breakages and interferrences between filter lists. The quality of the selected filter lists also affects the likelihood of website breakage. The EasyList and AdGuard -related filter lists are high-quality filter lists, as they are actively maintained. Hence to avoid possible websites breakages and interferrences between different filter lists, some non-uBlock filter lists are unchecked by default and need to be manually enabled by users at their own risk, and breakages caused by such additional filters lists are to be reported to issue trackers of the lists, for example: https://github.com/easylist/easylist or https://github.com/AdguardTeam/AdguardFilters, because https://github.com/uBlockOrigin/uAssets tracker is mainly reserved for issues related to uBlock's stock filter lists.

AdGuard filter lists in uBlock

Given a fact that both uBlock and AdGuard, are similiar-purposed blockers and have high compatibility with each other, there are several AdGuard's filter lists available in uBlock.

However keep in mind that some of them are slightly modified and adapted by AdGuard for better compatibility with uBlock, as a result, they might be stored separately from each other, for example AdGuard – Ads (Base Filter) list used by AdGuard browser extensions is stored in: LINK for AdGuard, while AdGuard – Ads used in uBlock is stored in: LINK for uBlock.

Additionaly, AdGuard – Ads (Base Filter) list in AdGuard is combined with EasyList, while in uBlock, EasyList and AdGuard – Ads exist separately.

Also, 100% compatibility all the time between uBO and AG extensions, even when using the same filter list, is not guaranteed, because some filters might be just not 100% compatible, like it's not guaranteed that the same website will work/look 100% same in different browsers (for example: Firefox vs Chrome), related issue: Same filters and diff extensions but diff results, why?

By the way, there is also ongoing discussion regarding supporting uBlock filter lists in AdGuard: Add «uBlock Filters».

Block Outsider Intrusion into LAN

More information in related discussions:

The discussion / issues should be continued in already existing main discussion threads, there is no point in spamming the issue tracker by creating new duplicates over and over, new threads will be labeled as invalid or duplicate and closed.


3rd-party filter lists

Adding Manually

To add a 3rd-party filter list, place a checkmark next to Import under the Custom section near the bottom of the Filter lists pane. Paste the URL of the filter list into the text area that appears below. (You can add multiple filter lists at once; however, only one URL per line. Invalid URLs will be silently ignored). These filter lists are automatically updated regularly.

custom-filter-lists

To remove a 3rd-party filter list, click the trash can icon at the end of the filter list name. Then click on the Apply changes button. The removed filter list will disappear.

Adding via Approved External Websites

You can subscribe to 3rd-party filter lists by clicking on a link for them on these approved external websites.

https://easylist.to/*
https://*.fanboy.co.nz/*
https://filterlists.com/*
https://forums.lanik.us/*
https://github.com/*
https://*.github.io/
https://*.letsblock.it/* - New in 1.41.7b0. Removed in 1.57.1b3.

This list is not intended to be expanded.

Adding via Right-click

You can subscribe to 3rd-party filter lists by right-clicking on a link for them and selecting "Subscribe to filter list..." from the contextual menu. This works regardless of the site on which the link is hosted.

Links to filter lists may be of the following forms:

abp:subscribe?location=encoded-url&title=optional-encoded-title
ubo:subscribe?location=encoded-url&title=optional-encoded-title
https://subscribe.adblockplus.org/?location=encoded-url&title=optional-encoded-title

For example, https://subscribe.adblockplus.org/?location=https%3A%2F%2Fraw.githubusercontent.com%2Fgorhill%2FuBlock%2Fmaster%2Fdocs%2Ftests%2Fstatic-filtering-parser-checklist.txt&title=Static%20Filtering%20Parser%20Checklist.

Clone this wiki locally