File: README.md Copy Chapter

uBlock Origin (uBO)

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

uBlock Origin (uBO) is a CPU and memory-efficient wide-spectrum content blocker for Chromium and Firefox. It blocks ads, trackers, coin miners, popups, annoying anti-blockers, malware sites, etc., by default using EasyList, EasyPrivacy, Peter Lowe's Blocklist, Online Malicious URL Blocklist, and uBO filter lists. There are many other lists available to block even more. Hosts files are also supported. uBO uses the EasyList filter syntax and extends 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
• Installation
  • Firefox
  • Chromium
  • Thunderbird
  • All Programs
  • Enterprise Deployment
• Release History
• Translations
• About

Documentation Copy Chapter

Visit the Wiki for documentation.

For support, questions, or help, visit /r/uBlockOrigin.

Installation Copy Chapter

Required Permissions

Firefox

Firefox Add-ons

Development Builds

uBO works best on Firefox and is available for desktop and Android versions.

Chromium

Chrome Web Store (Removal on 2026-08-31)

Microsoft Edge Add-ons (Published by Nicole Rolls until version 1.62. Ownership transfer at version 1.64.)

Opera Add-ons

Development Builds

uBO should be compatible with any Chromium-based browser.

Thunderbird

Thunderbird Add-ons

In Thunderbird, uBlock Origin does not affect emails, just feeds.

All Programs

Do NOT use uBO with any other content blocker. uBO performs 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

Enterprise Deployment

Deploying uBO

Release History Copy Chapter

Releases Page

Translations Copy Chapter

Help translate uBO via Crowdin.

About Copy Chapter

Manifesto

Privacy Policy

GPLv3 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.

File: platform/npm/README.md Copy Chapter

uBlock Origin Core

The core filtering engines used in the uBlock Origin ("uBO") extension, and has
no external dependencies.

Installation Copy Chapter

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.

Description Copy Chapter

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,
uBlock filters,
and also lists of domain names or hosts file format (i.e. block lists from The Block List Project,
Steven Black's HOSTS, etc).

Usage Copy Chapter

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:

import { StaticNetFilteringEngine } from '@gorhill/ubo-core';

If you must import as a NodeJS module:

const { StaticNetFilteringEngine } = await import('@gorhill/ubo-core');

Create an instance of SNFE:

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):

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:

// 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:

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:

const snfe = await StaticNetFilteringEngine.create();
await snfe.deserialize(serializedData);

Extras Copy Chapter

You can directly use specific APIs exposed by this package, here are some of
them, which are used internally by uBO's SNFE.

HNTrieContainer Copy Section

A well optimised compressed trie
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:

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.

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 Copy Chapter

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 https://github.com/RPGillespie6/codemirror-quickstart
• 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 Copy Chapter

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 Copy Chapter

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? Copy Section

See Documentation.

The Unlicense Copy Section

Contributions welcome.

Contact Copy Section

Reachable via chris.m.simpson [at] icloud.com or tweet @ChrisMSimpson.

Support Copy Section

There is none. Oh, you meant support me? I dare you to click the sponsor button above.

File: src/js/wasm/README.md Copy Chapter

For code reviewers Copy Section

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 Copy Section

The wat2wasm tool can be downloaded from an official WebAssembly project:
https://github.com/WebAssembly/wabt/releases/tag/1.0.29

`wat2wasm` tool online Copy Section

You can also use the following online wat2wasm tool:
https://webassembly.github.io/wabt/demo/wat2wasm/.

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 Copy Chapter

For code reviewers Copy Section

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 Copy Section

The wat2wasm tool can be downloaded from an official WebAssembly project:
https://github.com/WebAssembly/wabt/releases.

`wat2wasm` tool online Copy Section

You can also use the following online wat2wasm tool:
https://webassembly.github.io/wabt/demo/wat2wasm/.

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 Copy Section

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 Copy Chapter

Purpose Copy Chapter

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 Copy Chapter

`lz4-block-codec-any.js` Copy Section

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` Copy Section

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` Copy Section

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` Copy Section

This is the WebAssembly module, loaded by lz4-block-codec-wasm.js using a
same-origin fetch.

`lz4-block-codec.wat` Copy Section

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 https://github.com/WebAssembly/wabt, and wasm-opt at https://github.com/WebAssembly/binaryen.