This page describes the uBlock Origin repository at gorhill/uBlock: what it builds, what major subsystems it contains, and how those subsystems relate to each other. The current release version is 1.69.1.5 (dist/version1).
This page is a high-level orientation. For details on specific subsystems, see the child pages: architecture in 1.1, key terminology in 1.2, the build and release system in 2, and the filtering engine in 3.
The repository produces three distinct outputs from a shared source base:
| Output | Description | Target |
|---|---|---|
| uBlock Origin (MV2) | Classic content-blocking extension using webRequest | Firefox, Chromium, Edge, Opera, Thunderbird |
| uBOLite (MV3) | Lite extension using Declarative Net Request (DNR) | Chrome, Edge, Firefox, Safari |
@gorhill/ubo-core | npm package exposing the static network filtering engine | Node.js consumers |
uBlock Origin (MV2) and uBOLite (MV3) have fundamentally different runtime architectures despite sharing filter list assets and most of the parsing/compilation logic. See 10 for a full treatment of uBOLite.
Sources: README.md1-40 dist/version1 platform/npm/package.json1-35
Top-level directory structure:
| Directory / File | Role |
|---|---|
src/js/ | Shared JavaScript source for background, content scripts, and UI |
src/css/ | Stylesheets for extension UI pages |
src/img/ | Icons and images |
assets/ | Filter list registry (assets.json) and bundled filter lists |
platform/ | Per-platform build adapters (chromium, firefox, mv3, npm, dig) |
dist/ | Build outputs and version file |
tools/ | Build helper scripts |
_locales/ | Internationalization message files |
Makefile | Top-level build orchestration |
.github/workflows/ | CI/CD pipeline definitions |
Sources: README.md40-135 tools/pull-assets.sh1-11 .gitmodules1-7
Figure 1: Build targets and their source inputs
Sources: dist/version1 tools/pull-assets.sh1-11 platform/npm/package.json1-35 .gitmodules1-7
The MV2 extension runs three categories of JavaScript contexts simultaneously: a persistent background page, per-tab content scripts, and UI pages (popup, dashboard, logger). All cross-context communication flows through a single messaging layer.
Figure 2: Runtime contexts and their primary source files
Sources: README.md30-40
The filtering system is composed of several cooperating engines, each responsible for a different class of filter rule. All engines are compiled from raw filter list text at startup.
Figure 3: Filtering engine components and their source files
| Engine | Source File | Handles |
|---|---|---|
StaticNetFilteringEngine | src/js/static-net-filtering.js | URL pattern matching — block, allow, redirect |
CosmeticFilteringEngine | src/js/cosmetic-filtering.js | CSS selector injection and element hiding |
ScriptletFilteringEngineEx | src/js/scriptlet-filtering.js | JavaScript snippet injection |
HTMLFilteringEngine | src/js/html-filtering.js | Response body DOM filtering |
StaticExtFilteringEngine | src/js/static-ext-filtering.js | Dispatch for all extended filter types |
| Dynamic net filtering | src/js/dynamic-net-filtering.js | Per-user firewall rules and per-site switches |
Sources: docs/tests/static-filtering-parser-checklist.txt1-20
The two products differ fundamentally in how they intercept network requests:
| Aspect | MV2 — uBlock Origin | MV3 — uBOLite |
|---|---|---|
| Background context | Persistent background page | Ephemeral service worker |
| Request interception | browser.webRequest (dynamic, full access) | Declarative Net Request (DNR) rulesets, pre-compiled |
| Filter compilation | At runtime, on startup | At build time via make-rulesets.js |
| Cosmetic filters | Full support via content scripts | Injected CSS from pre-built lists |
| Scriptlets | Dynamic injection per hostname | Pre-compiled, permission-gated |
| User custom filters | Fully supported | Limited; requires host permissions |
| Dynamic firewall | Full per-site firewall | Not available |
| Main source directory | src/js/ + platform/chromium/ or platform/firefox/ | platform/mv3/ |
For detailed MV3 architecture, see 10.1. For the MV3 ruleset generation pipeline, see 10.2.
| File | Role |
|---|---|
src/js/background.js | Registers background service worker or persistent background page |
src/js/start.js | Orchestrates MV2 initialization sequence |
src/js/ublock.js | Defines the µb singleton — the central shared state object |
src/js/traffic.js | webRequest listener that drives all network filtering |
src/js/messaging.js | Central IPC hub routing all inter-context messages |
src/js/contentscript.js | Injected into every web page; bootstraps DOM-side filtering |
assets/assets.json | Registry of all built-in and third-party filter lists |
platform/mv3/extension/js/background.js | MV3 service worker entry point |
platform/npm/index.js | npm package entry point for @gorhill/ubo-core |
@gorhill/ubo-coreThe repository also publishes a standalone npm package (platform/npm/package.json1-35) under the name @gorhill/ubo-core (version 0.1.30). It exposes the static network filtering engine (StaticNetFilteringEngine) for use in Node.js environments — for example, to run filter list matching outside of a browser extension context. It requires Node.js ≥ 18. See 11.1 for the associated benchmarking and development tooling.
uBlock Origin is released under the GPLv3 license. It accepts no donations. Translation contributions are managed through Crowdin. Filter list maintenance is handled separately in the uBlockOrigin/uAssets repository, which is pulled into builds via tools/pull-assets.sh.
Sources: README.md124-134 package.json1-32 tools/pull-assets.sh1-11
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.