## File: README.md [![Badge Commits]][Commit Rate] [![Badge Issues]][Issues] [![Badge Localization]][Crowdin] [![Badge License]][License] [![Badge NPM]][NPM] [![Badge Mozilla]][Mozilla] [![Badge Chrome]][Chrome] [![Badge Edge]][Edge] ***

uBlock Origin (uBO)

| Browser | Install from ... | Status | | :-------: | ---------------- | ------ | | | [Firefox Add-ons](https://addons.mozilla.org/addon/ublock-origin/) | [uBO works best on Firefox](https://github.com/gorhill/uBlock/wiki/uBlock-Origin-works-best-on-Firefox) | | | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/ublock-origin/odfafepnkmbhccpbejgmiehpchacaeak) | ["Moving the Microsoft Edge extensions ecosystem forward with Manifest Version 3"](https://blogs.windows.com/msedgedev/2026/08/07/moving-the-microsoft-edge-extensions-ecosystem-forward-with-manifest-version-3/): "Beginning in August 2026, Microsoft Edge will start the consumer transition away from Manifest Version 2 (MV2) extensions and toward MV3. Our goal is to complete the consumer transition by the end of 2026, with enterprise deprecation following in early 2027." | | | [Opera Add-ons](https://addons.opera.com/extensions/details/ublock/) | | | [Chrome Web Store](https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm) | ["Manifest V2 support timeline"](https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline#aug_31st_2026_all_remaining_manifest_v2_extensions_removed_from_the_chrome_web_store): "Aug 31st 2026: All remaining Manifest V2 extensions removed from the Chrome Web Store"[About Google Chrome's "This extension may soon no longer be supported"](https://github.com/uBlockOrigin/uBlock-issues/wiki/About-Google-Chrome) | | | [Thunderbird Add-ons](https://addons.thunderbird.net/thunderbird/addon/ublock-origin/) | [No longer updated and stuck at 1.49.2.](https://github.com/uBlockOrigin/uBlock-issues/issues/2928) Later versions require "GitHub - Releases". | | | [GitHub - Releases](https://github.com/gorhill/uBlock/releases) | Stable and development versions on Firefox, Chromium MV2, and Thunderbird. Must be placed manually into web browsers; the Chromium and Thunderbird versions usually won't auto-update.

Related: [uBlock Origin Lite](https://github.com/uBlockOrigin/uBOL-home)

*** uBlock Origin (uBO) is a CPU and memory-efficient [wide-spectrum content blocker][Blocking] for Chromium and Firefox. It blocks ads, trackers, coin miners, popups, annoying anti-blockers, malware sites, etc., by default using [EasyList][EasyList], [EasyPrivacy][EasyPrivacy], [Peter Lowe's Blocklist][Peter Lowe's Blocklist], [Online Malicious URL Blocklist][Malicious Blocklist], and uBO [filter lists][uBO Filters]. There are many other lists available to block even more. Hosts files are also supported. uBO uses the EasyList filter syntax and [extends][Extended Syntax] the syntax to work with custom rules and filters. You may easily unselect any preselected filter lists if you think uBO blocks too much. For reference, Adblock Plus installs with only EasyList, ABP filters, and Acceptable Ads enabled by default. It is important to note that using a blocker is **NOT** [theft]. Do not fall for this creepy idea. The _ultimate_ logical consequence of `blocking = theft` is the criminalization of the inalienable right to privacy. Ads, "unintrusive" or not, are just the visible portion of the privacy-invading means entering your browser when you visit most sites. **uBO's primary goal is to help users neutralize these privacy-invading methods** in a way that welcomes those users who do not wish to use more technical means. *** * [Documentation](#documentation) * [Installation](#installation) * [Firefox](#firefox) * [Chromium](#chromium) * [Thunderbird](#thunderbird) * [All Programs](#all-programs) * [Enterprise Deployment](#enterprise-deployment) * [Release History](#release-history) * [Translations](#translations) * [About](#about) ## Documentation | Basic Mode | Advanced Mode | | --- | --- | | The [simple popup user interface](https://github.com/gorhill/uBlock/wiki/Quick-guide:-popup-user-interface) for an install-it-and-forget-it type of installation that is configured optimally by default. | The [advanced popup user interface](https://github.com/gorhill/uBlock/wiki/Dynamic-filtering:-quick-guide) includes a point-and-click firewall that is configurable on a per-site basis. | | [](https://github.com/gorhill/uBlock/wiki/Quick-guide:-popup-user-interface) | [](https://github.com/gorhill/uBlock/wiki/Dynamic-filtering:-quick-guide) | Visit the [Wiki][Wiki] for documentation. For support, questions, or help, visit [/r/uBlockOrigin][Reddit]. ## Installation [Required Permissions][Permissions] #### Firefox [Firefox Add-ons][Mozilla] [Development Builds][Beta] uBO [works best][Works Best] on Firefox and is available for desktop and Android versions. #### Chromium [Chrome Web Store][Chrome] (Removal on 2026-08-31) [Microsoft Edge Add-ons][Edge] (Published by [Nicole Rolls][Nicole Rolls] until version 1.62. Ownership transfer at version 1.64.) [Opera Add-ons][Opera] [Development Builds][Chrome Dev] uBO should be compatible with any Chromium-based browser. #### Thunderbird [Thunderbird Add-ons][Thunderbird] In Thunderbird, uBlock Origin does not affect emails, just feeds. #### All Programs Do **NOT** use uBO with any other content blocker. uBO [performs][Performance] as well as or better than most popular blockers. Other blockers can prevent uBO's privacy or anti-blocker-defusing features from working correctly. [Manual Installation][Manual Installation] #### Enterprise Deployment [Deploying uBO][Deployment] ## Release History [Releases Page][Releases] ## Translations Help translate uBO via [Crowdin][Crowdin]. ## About [Manifesto][Manifesto] [Privacy Policy][Privacy Policy] [GPLv3 License][License] Free. Open-source. For users by users. No donations sought. If you ever want to contribute something, think about the people working hard to maintain the filter lists you are using, which are available to use by all for free. [Peter Lowe's Blocklist]: https://pgl.yoyo.org/adservers/ [Malicious Blocklist]: https://gitlab.com/malware-filter/urlhaus-filter#malicious-url-blocklist [Performance]: https://www.debugbear.com/blog/chrome-extensions-website-performance#the-impact-of-ad-blocking-on-website-performance [EasyPrivacy]: https://easylist.to/#easyprivacy [Thunderbird]: https://addons.thunderbird.net/thunderbird/addon/ublock-origin/ [Chrome Dev]: https://chromewebstore.google.com/detail/ublock-origin-development/cgbcahbpdhpcegmbfconppldiemgcoii [EasyList]: https://easylist.to/#easylist [Mozilla]: https://addons.mozilla.org/addon/ublock-origin/ [Crowdin]: https://crowdin.com/project/ublock [Chrome]: https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm [Reddit]: https://www.reddit.com/r/uBlockOrigin/ [Theft]: https://x.com/LeaVerou/status/518154828166725632 [Opera]: https://addons.opera.com/extensions/details/ublock/ [Edge]: https://microsoftedge.microsoft.com/addons/detail/ublock-origin/odfafepnkmbhccpbejgmiehpchacaeak [NPM]: https://www.npmjs.com/package/@gorhill/ubo-core [Manifesto]: MANIFESTO.md [License]: LICENSE.txt [Nicole Rolls]: https://github.com/nicole-ashley [Manual Installation]: https://github.com/gorhill/uBlock/tree/master/dist#install [Extended Syntax]: https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#extended-syntax [Privacy Policy]: https://github.com/gorhill/uBlock/wiki/Privacy-policy [uBO Filters]: https://github.com/uBlockOrigin/uAssets/tree/master/filters [Permissions]: https://github.com/gorhill/uBlock/wiki/Permissions [Commit Rate]: https://github.com/gorhill/uBlock/commits/master [Works Best]: https://github.com/gorhill/uBlock/wiki/uBlock-Origin-works-best-on-Firefox [Deployment]: https://github.com/gorhill/uBlock/wiki/Deploying-uBlock-Origin [Blocking]: https://github.com/gorhill/uBlock/wiki/Blocking-mode [Releases]: https://github.com/gorhill/uBlock/releases [Issues]: https://github.com/uBlockOrigin/uBlock-issues/issues [Beta]: https://github.com/gorhill/uBlock/blob/master/dist/README.md#for-beta-version [Wiki]: https://github.com/gorhill/uBlock/wiki [Badge Localization]: https://d322cqt584bo4o.cloudfront.net/ublock/localized.svg [Badge Commits]: https://img.shields.io/github/commit-activity/m/gorhill/ublock?label=Commits [Badge Mozilla]: https://img.shields.io/amo/rating/ublock-origin?label=Firefox [Badge License]: https://img.shields.io/badge/License-GPLv3-blue.svg [Badge Chrome]: https://img.shields.io/chrome-web-store/rating/cjpalhdlnbpafiamejdnhcphjbkeiagm?label=Chrome [Badge Edge]: https://img.shields.io/badge/dynamic/json?label=Edge&color=brightgreen&query=%24.averageRating&suffix=%2F%35&url=https%3A%2F%2Fmicrosoftedge.microsoft.com%2Faddons%2Fgetproductdetailsbycrxid%2Fodfafepnkmbhccpbejgmiehpchacaeak [Badge Issues]: https://img.shields.io/github/issues/uBlockOrigin/uBlock-issues [Badge NPM]: https://img.shields.io/npm/v/@gorhill/ubo-core --- ## File: platform/npm/README.md # uBlock Origin Core The core filtering engines used in the uBlock Origin ("uBO") extension, and has no external dependencies. ## Installation Install: `npm install @gorhill/ubo-core` This is a very early version and the API is subject to change at any time. This package uses [native JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). ## Description The package contains uBO's static network filtering engine ("SNFE"), which purpose is to parse and enforce filter lists. The matching algorithm is highly efficient, and _especially_ optimized to match against large sets of pure hostnames. The SNFE can be fed filter lists from a variety of sources, such as [EasyList/EasyPrivacy](https://easylist.to/), [uBlock filters](https://github.com/uBlockOrigin/uAssets/tree/master/filters), and also lists of domain names or hosts file format (i.e. block lists from [The Block List Project](https://github.com/blocklistproject/Lists#the-block-list-project), [Steven Black's HOSTS](https://github.com/StevenBlack/hosts#readme), etc). ## Usage See `./demo.js` in package for instructions to quickly get started. At the moment, there can be only one instance of the static network filtering engine ("SNFE"), which proxy API must be imported as follow: ```js import { StaticNetFilteringEngine } from '@gorhill/ubo-core'; ``` If you must import as a NodeJS module: ```js const { StaticNetFilteringEngine } = await import('@gorhill/ubo-core'); ``` Create an instance of SNFE: ```js const snfe = await StaticNetFilteringEngine.create(); ``` Feed the SNFE with filter lists -- `useLists()` accepts an array of objects (or promises to object) which expose the raw text of a list through the `raw` property, and optionally the name of the list through the `name` property (how you fetch the lists is up to you): ```js await snfe.useLists([ fetch('easylist').then(r => r.text()).then(raw => ({ name: 'easylist', raw })), fetch('easyprivacy').then(r => r.text()).then(raw => ({ name: 'easyprivacy', raw })), ]); ``` Now we are ready to match network requests: ```js // Not blocked if ( snfe.matchRequest({ originURL: 'https://www.bloomberg.com/', url: 'https://www.bloomberg.com/tophat/assets/v2.6.1/that.css', type: 'stylesheet' }) !== 0 ) { console.log(snfe.toLogData()); } // Blocked if ( snfe.matchRequest({ originURL: 'https://www.bloomberg.com/', url: 'https://securepubads.g.doubleclick.net/tag/js/gpt.js', type: 'script' }) !== 0 ) { console.log(snfe.toLogData()); } // Unblocked if ( snfe.matchRequest({ originURL: 'https://www.bloomberg.com/', url: 'https://sourcepointcmp.bloomberg.com/ccpa.js', type: 'script' }) !== 0 ) { console.log(snfe.toLogData()); } ``` Once all the filter lists are loaded into the static network filtering engine, you can serialize the content of the engine into a JS string: ```js const serializedData = await snfe.serialize(); ``` You can save and later use that JS string to fast-load the content of the static network filtering engine without having to parse and compile the lists: ```js const snfe = await StaticNetFilteringEngine.create(); await snfe.deserialize(serializedData); ``` --- ## Extras You can directly use specific APIs exposed by this package, here are some of them, which are used internally by uBO's SNFE. ### HNTrieContainer A well optimised [compressed trie](https://en.wikipedia.org/wiki/Trie#Compressing_tries) container specialized to specifically store and lookup hostnames. The matching algorithm is designed for hostnames, i.e. the hostname labels making up a hostname are matched from right to left, such that `www.example.org` with be a match if `example.org` is stored into the trie, while `anotherexample.org` won't be a match. `HNTrieContainer` is designed to store a large number of hostnames with CPU and memory efficiency as a main concern -- and is a key component of uBO. To create and use a standalone `HNTrieContainer` object: ```js import HNTrieContainer from '@gorhill/ubo-core/js/hntrie.js'; const trieContainer = new HNTrieContainer(); const aTrie = trieContainer.createOne(); trieContainer.add(aTrie, 'example.org'); trieContainer.add(aTrie, 'example.com'); const anotherTrie = trieContainer.createOne(); trieContainer.add(anotherTrie, 'foo.invalid'); trieContainer.add(anotherTrie, 'bar.invalid'); // matches() return the position at which the match starts, or -1 when // there is no match. // Matches: return 4 console.log("trieContainer.matches(aTrie, 'www.example.org')", trieContainer.matches(aTrie, 'www.example.org')); // Does not match: return -1 console.log("trieContainer.matches(aTrie, 'www.foo.invalid')", trieContainer.matches(aTrie, 'www.foo.invalid')); // Does not match: return -1 console.log("trieContainer.matches(anotherTrie, 'www.example.org')", trieContainer.matches(anotherTrie, 'www.example.org')); // Matches: return 0 console.log("trieContainer.matches(anotherTrie, 'foo.invalid')", trieContainer.matches(anotherTrie, 'foo.invalid')); ``` The `reset()` method must be used to remove all the tries from a trie container, you can't remove a single trie from the container. ```js trieContainer.reset(); ``` When you reset a trie container, you can't use the reference to prior instances of trie, i.e. `aTrie` and `anotherTrie` are no longer valid and shouldn't be used following a reset. --- ## File: platform/mv3/extension/lib/codemirror/README.md Steps to build `cm6.bundle.ubol.min.js` -- command line from repo root: - `git submodule init platform/mv3/extension/lib/codemirror/codemirror-ubol` - `cd platform/mv3/extension/lib/codemirror/codemirror-ubol/` - We are now in a customized repo forked from - `npm install` - `npm run build` - `cm6.bundle.ubol.min.js` should be in `dist` directory - This is the origin of the `cm6.bundle.ubol.min.js` in the current directory --- ## File: platform/mv3/README.md # How to build MV3 uBO Lite Instructions for reviewers. The following assumes a linux environment. 1. Open Bash console 2. `git clone https://github.com/gorhill/uBlock.git` 3. `cd uBlock` 4. `git submodule init` 5. `git submodule update` 6. `make mv3-[platform]`, where `[platform]` is either `chromium`, `edge`, `firefox`, or `safari` 7. This will fully build uBO Lite, and during the process filter lists will be downloaded from their respective remote servers Upon completion of the script, the resulting extension package will become present in: - Chromium: `dist/build/uBOLite.chromium` - Edge: `dist/build/uBOLite.edge` - Firefox: `dist/build/uBOLite.firefox` - Safari: `dist/build/uBOLite.safari` The folder `dist/build/mv3-data` will cache data fetched from remote servers, so as to avoid fetching repeatedly from remote servers with repeated build commands. Use `make cleanassets` to remove all locally cached filter lists if you want to build with latest versions of filter lists. The file `dist/build/uBOLite.[platform]/log.txt` will contain information about what happened during the build process. The entry in the `Makefile` which implement the build process is `tools/make-mv3.sh [platform]`.[1] This Bash script copy various files from uBlock Origin branch and MV3-specific branch into a single folder which will be the final extension package. Notably, `tools/make-mv3.sh [platform]` calls a Nodejs script which purpose is to convert the filter lists into various rulesets to be used in a declarative way. The Nodejs version required is 17.5.0 or above. All the final rulesets are present in the `dist/build/uBOLite.[platform]/rulesets` in the final extension package. --- [1] https://github.com/gorhill/uBlock/blob/c4d324362fdb95ff8ef20f0b18f42f0eec955433/tools/make-mv3.sh --- ## File: src/css/fonts/Metropolis/README.md # Metropolis A modern, geometric typeface. Influenced by other popular geometric, minimalist sans-serif typefaces of the new millennium. Designed for optimal readability at small point sizes while beautiful at large point sizes. --- ### Where am I? See [Documentation](./Documentation/Documentation.md). ### The Unlicense Contributions welcome. ### Contact Reachable via chris.m.simpson [at] icloud.com or tweet @ChrisMSimpson. ### Support There is none. Oh, you meant support me? I dare you to click the sponsor button above. --- ## File: src/js/wasm/README.md ### For code reviewers All `wasm` files in that directory where created by compiling the corresponding `wat` file using the command (using `hntrie.wat`/`hntrie.wasm` as example): wat2wasm hntrie.wat -o hntrie.wasm Assuming: - The command is executed from within the present directory. ### `wat2wasm` tool The `wat2wasm` tool can be downloaded from an official WebAssembly project: ### `wat2wasm` tool online You can also use the following online `wat2wasm` tool: . Just paste the whole content of the `wat` file to compile into the WAT pane. Click "Download" button to retrieve the resulting `wasm` file. --- ## File: src/lib/publicsuffixlist/wasm/README.md ### For code reviewers All `wasm` files in that directory where created by compiling the corresponding `wat` file using the command (using `publicsuffixlist.wat`/`publicsuffixlist.wasm` as example): wat2wasm publicsuffixlist.wat -o publicsuffixlist.wasm Assuming: - The command is executed from within the present directory. ### `wat2wasm` tool The `wat2wasm` tool can be downloaded from an official WebAssembly project: . ### `wat2wasm` tool online You can also use the following online `wat2wasm` tool: . Just paste the whole content of the `wat` file to compile into the WAT pane. Click "Download" button to retrieve the resulting `wasm` file. ### See also For the curious, the following online tool allows you to find out the machine code as a result from the WASM code: https://mbebenita.github.io/WasmExplorer/ --- ## File: src/lib/lz4/README.md ## Purpose The purpose of this library is to implement LZ4 compression/decompression, as documented at the official LZ4 repository: https://github.com/lz4/lz4/blob/dev/doc/lz4_Block_format.md The files in this directory are developed as a separate project at: https://github.com/gorhill/lz4-wasm ## Files ### `lz4-block-codec-any.js` The purpose is to instantiate a WebAssembly- or pure javascript-based LZ4 block codec. If the chosen implementation is not specified, there will be an attempt to create a WebAssembly-based instance. If for whatever reason this fails, a pure javascript-based instance will be created. The script for either instance are dynamically loaded and only when needed, such that no resources are wasted by keeping in memory code which won't be used. ### `lz4-block-codec-wasm.js` This contains the code to instantiate WebAssembly-based LZ4 block codec. Note that the WebAssembly module is loaded using a `same-origin` fetch, hence ensuring that no code outside the package is loaded. ### `lz4-block-codec-js.js` This contains the code to instantiate pure javascript-based LZ4 block codec. This is used as a fallback implementation should WebAssembly not be available for whatever reason. ### `lz4-block-codec.wasm` This is the WebAssembly module, loaded by `lz4-block-codec-wasm.js` using a `same-origin` fetch. ### `lz4-block-codec.wat` The WebAssembly source code used to generate the WebAssembly module `lz4-block-codec.wasm`. wat2wasm ./lz4-block-codec.wat -o ./lz4-block-codec.wasm wasm-opt ./lz4-block-codec.wasm -O4 -o ./lz4-block-codec.wasm You can get `wat2wasm` at , and `wasm-opt` at .