Document your code
Every project on GitHub comes with a version-controlled wiki to give your documentation the high level of care it deserves. It’s easy to create well-maintained, Markdown or rich text documentation alongside your code.
Sign up for free See pricing for teams and enterprisesAdvanced settings
The "Advanced settings" page contains settings which are experimental, or which are of interest to advanced users who want more control over how uBO behaves internally.
These advanced settings can be easily accessed only when the setting "I am an advanced user" in the Settings pane in the dashboard is checked, but will persist and work even when the setting "I am an advanced user" is not checked:
The advanced settings available are described below. Be aware that those settings may change or be removed in the future, or more may be added.
If you want to reset a specific setting to its default value, just delete the value, uBO will fill the missing value with the default one.
If you want to reset all settings to their default values, delete everything then press "Apply changes".
allowGenericProceduralFilters
Default: false.
uBO 1.19.3b8 and above.
If set to true, generic procedural cosmetic filters will no longer be discarded as invalid.
Whenever this setting is toggled, the user is responsible of forcing a reload of all filter lists so as to allow uBO to process differently any existing generic procedural cosmetic filters.
assetFetchTimeout
Default: 30 seconds.
The number of seconds after which uBO throws an error when a remote server fails to respond to a request.
autoCommentFilterTemplate
Default value is {{date}} {{origin}}.
uBO 1.17.7b2 and above.
Placeholders are identified by {{...}}. There are currently
only three placeholders supported:
-
{{date}}: will be replaced with current date -
{{time}}: will be replaced with current time -
{{origin}}: will be replaced with site information on which the filter(s) was created
If no placeholder is found in autoCommentFilterTemplate, this
will disable auto-commenting. So one can use - or none to disable
auto-commenting.
autoUpdateAssetFetchPeriod
Default: 120 seconds.
When the auto-updater kicks in and an asset in need of update is fetched, this is the number of seconds to wait before fetching the next asset which needs to be updated. The delay helps spread the load on CPU and memory as a result of loading/parsing/compiling the filter lists which have been updated.
autoUpdateDelayAfterLaunch
Default: 180 secs.
uBO 1.19.3b9 and above.
The number of seconds to wait after launch before an auto-update session[1] is started.
[1] "Update session" means that uBO will lookup and update assets deemed out of date, if any.
autoUpdatePeriod
Default: 7 hours.
The time to wait in hours between each update session. uBO will always start an update session a few minutes after launch when auto-update is enabled. Once that first update session is completed, uBO will wait autoUpdatePeriod hours before starting a new update session.
blockingProfiles
Default: 11111/#F00 11011/#C0F 11001/#00F 00001
Before 1.21.7b6: 11101 11001 00001
Introduced in 1.21.0, improved after 1.21.7b6 to reflect blocking mode in the color of uBlock₀ icon badge.
Preference allows to configure cascade of the "Relax blocking mode" keyboard shortcut, along with corresponding badge color.
Default value contains four codes separated by space representing four blocking modes:
| Hard mode + No scripting |
Medium mode + No scripting |
Medium mode | Default |
|---|---|---|---|
| 11111/#F00 | 11011/#C0F | 11001/#00F | 00001 |
 |
 |
 |
 |
Each code consist of bit field indicating status of the feature ( 1 for blocked/enabled, 0 for not blocked/disabled ) and optional separator / followed by CSS color value[1].
| 3p-frame | 3p-script | 3p | no-scripting | reload action | separator | CSS color value[1] |
|---|
Pressing "Relax blocking mode" will compare current uBO status with blockingProfiles codes from left to right and apply if it's different, then reload page if "reload action" is enabled, then apply color to the uBO icon badge.
cacheControlForFirefox1376932
Default: no-cache, no-store, must-revalidate.
uBO 1.17.0 and above.
Configure how uBO should affect caching for the purpose of dealing with browser bug (see #229).
Possible values:
-
no-cache, no-store, must-revalidate:- Undesirable side effect: documents themselves for which uBO has to inject CSP directives as a result of filters/ruleset won't be available offline.
-
no-cache:- Undesirable side effect: One will need to explicitly cache-bypass reload a page each time uBO has to inject CSP directives as a result of filters/ruleset. Note that such cache-bypass reload does not affect only the document itself, but also all secondary resources inside that document.
-
unset:- Available after 1.21.7b7, turns off this path.
Related browser issues:
cacheStorageAPI
Default: unset.
After 1.18.5b4 works in Firefox.
If set to browser.storage.local, uBO will use WebExtensions storage as a backend to cache storage.
Additionally, should indexedDB not be available for whatever reason,
uBO will automatically fallback to browser.storage.local.
uBO 1.18.2 and above, Chromium only.
If set to indexedDB, uBO will use IndexedDB as a backend to the cache storage, potentially increasing performance and reducing memory usage. See #328 for details.
Bad side effects - filter lists will be out of date in Chrome incognito mode - #399.
If unset, uBO will use whatever backend storage which is optimal for the current platform.
cacheStorageCompression
Default: true.
uBO 1.16.21 and above.
If set to true, uBO will lz4-compress data before storing it in its cache storage. The cache storage is used for storing downloaded filter lists, compiled filter lists, selfies. This setting work when IndexedDB is used as the cache storage backend (by default with Firefox/Firefox for Android). See #141 for related discussion.
cnameIgnore1stParty
Default: true.
Introduced in 1.24.1b0 development versions.
cnameIgnoreExceptions
Default: true.
Introduced in 1.24.3b2 development versions.
cnameIgnoreList
Default: unset.
Introduced in 1.24.1b0 development versions.
cnameIgnoreRootDocument
Default: true.
Introduced in 1.24.3b1 development versions.
cnameMaxTTL
Default: 60 minutes.
Introduced in 1.24.1b0 development versions.
cnameReplayFullURL
Default: false.
Introduced in 1.24.3b1 development versions.
cnameUncloak
Default: true.
Introduced in 1.24.3b2 development versions.
consoleLogLevel
Default: unset.
uBO 1.18.5b1 and above
For development purposes only.
If set to info, prints debug messages to the browser console.
debugScriptlets
debugScriptletInjector
Default: false.
If set to true, debugger; statement will be inserted just before scriptlet or scriptlet injector code.
disableWebAssembly
Default: false.
uBO 1.17.3rc4 and above.
For development purposes only.
If set to true, turns off WebAssembly optimizations in uBO code.
extensionUpdateForceReload
Default: false.
uBO 1.23.3b3 and above.
If set to true, restores update behavior from before 1.22.3b ("Prevent uBO from being reloaded mid-session "), extension will unconditionally reload when an update is available; otherwise the extension will reload only when being explicitly disabled then enabled, or when the browser is restarted.
filterAuthorMode
Under development!! Do not create related issues!
Default: false.
uBO 1.23.0 and above.
Enabled point-and-click feature, to create temporary exception filters for static extended filters (i.e. cosmetic, scriptlet & html filters) from within the summary pane in the logger. The button to toggle on/off temporary exception filter is labeled #@#:
The created exceptions are temporary and will be lost when restarting uBO, or manually toggling off the exception filters.
ignoreRedirectFilters
Default: false.
If set to true, uBO will no longer attempt to redirect blocked network requests to a local, neutered version of a resource. The main purpose of redirect filters is to minimize web page breakage as a result of blocking resources.
ignoreScriptInjectFilters
Default: false.
If set to true, uBO will no longer lookup and inject scriptlets into web pages. The main purpose of the scriptlets is to defuse anti-blocker mechanisms present on some sites.
loggerPopupType
Default: popup.
uBO 1.22.1b3 and above.
Control the type of window to be used when the logger is launched as a separate window. Introduced to solve issues with missing/disabled titlebar buttons, resizing, incorrect drawing (#663).
Possible values:
-
popup- browser window without toolbars (default) -
normal- normal browser window with all toolbars and buttons - any other value defined in Chromium or Firefox documentation.
manualUpdateAssetFetchPeriod
Default: 500 milliseconds.
When clicking the "Update now" button in the "3rd-party filters" pane in the dashboard, this is the number of milliseconds to wait before fetching the next asset which needs to be updated. The delay helps spread the load incurred as a result of loading/processing new filter lists, and its purpose is also to be considerate to remote servers by not subjecting them to rapid-fire requests.
popupFontSize
Default: unset.
A valid CSS font size value (14px) to use for the popup panel. Use if you are unhappy with the default size.
requestJournalProcessPeriod
Default: 1000 milliseconds.
uBO 1.16.21b2 and above.
Controls the delay before uBO internally process it's network request journal queue. The network request journal queue exists for the purpose of fixing issue 2053.
As a benign side effect to the fix, there is a delay in displaying the number of blocked requests on extension icon (see #155).
A lower delay than the default one could bring back the issue it's meant to fix.
selfieAfter
Default: 3 minutes.
uBO 1.18.5b1 and above. Used to be 11 minutes until 1.19.7rc1.
Number of minutes after which selfie (optimized, internal representation of filters) is created.
strictBlockingBypassDuration
Default: 120 seconds.
uBO 1.17.3b4 and above.
Controls duration of the Strict blocking "Temporarily" bypass.
suspendTabsUntilReady (experimental)
Default: unset, before 1.18.5b8: false.
Possible values:
-
unset- leave it to the platform to pick the optimal behavior (default) -
no- do no suspend tab loading at launch time -
yes- suspend tab loading at launch time
After 1.18.5b8 configurable again in Firefox (can be disabled). After uBO 1.17.5rc0 - Chromium only. In Firefox this feature is always active thanks to "persistent startup listeners".
If enabled, uBO will hard block all network requests when the browser launches until all the filter lists and rules are loaded and ready, at which time uBO will force a reload of the tabs for which there were network requests blocked during the setup phase.
Disclaimer: especially in Chromium based browsers, even with this setting enabled, it's impossible for uBO to guarantee with 100% certainty that everything will be properly blocked when the browser is launched. This is a by-design browser issue -- do not open an issue on uBO issue tracker about this.
Related browser issues:
- Chromium: https://bugs.chromium.org/p/chromium/issues/detail?id=523634
- Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1378459, fixed by https://bugzilla.mozilla.org/show_bug.cgi?id=1447551.
updateAssetBypassBrowserCache
Default: false
With v1.21.7b1 and above.
If set to true, uBO will ensure the browser cache is bypassed when fetching a remote resource.
userResourcesLocation
Default: unset.
One or more space-separated URLs which content will be parsed as token-identified resources to be used for redirect or scriptlet-injection (+js(...)) purpose.
uBO expects valid content such as can be seen in resources.txt, anything else will lead to undefined results.
Any duplicate as per token will result in the previous resource being replaced by the latter one. The resource files are loaded in order of URL appearance, and uBO stock resource file is always loaded first.
Additional resources will be updated at the same time the built-in resource file is updated. Purging the cache of 'uBlock filters' will also purge the cache of the built-in resource file -- and hence force a reload of user-specified resources if any.
The setting was introduced in 1.12.0. Support for multiple URLs was introduced in 1.19.0.