# uBlock Origin — User Guide

uBlock Origin (uBO) is a free, open-source, wide-spectrum content blocker for web browsers. It efficiently blocks ads, trackers, malware domains, and other unwanted content using curated filter lists and user-defined rules — all while consuming significantly less memory and CPU than competing extensions. Created by Raymond Hill (gorhill) and licensed under GPLv3, uBO puts you in full control of what your browser loads.

---

## 1. Quick Start

### Get Blocking in 60 Seconds

1. **Install** uBlock Origin from your browser's official extension store (see [Section 2](#2-installation) for links).
2. **Done.** uBO ships with sensible defaults already enabled — EasyList, EasyPrivacy, Peter Lowe's Ad and tracking server list, and the uBlock filters suite. Ads and trackers are blocked immediately.
3. **Verify** by visiting any ad-heavy website. Click the uBO icon in the toolbar to see the popup panel showing blocked requests.

> [!TIP]
> uBlock Origin works out of the box with zero configuration. The default filter lists block the vast majority of ads and trackers on English-language sites. You only need to adjust settings if you want region-specific blocking, stricter privacy controls, or per-site customization.

### The Popup Panel at a Glance

When you click the uBO icon in your browser toolbar, you see the **popup panel** — your primary control surface:

| Element | What It Does |
|---|---|
| **Power button** (large blue shield) | Toggle uBO on/off for the current site |
| **Request counts** | Shows blocked requests / total requests for the current page |
| **Per-site switches** | Quick toggles for cosmetic filtering, JavaScript, etc. (advanced mode) |
| **Element picker** (eyedropper icon) | Point-and-click to hide a specific page element |
| **Element zapper** (lightning bolt icon) | Temporarily remove a page element (does not persist) |
| **Logger** (list icon) | Open the real-time network request logger |
| **Dashboard** (gear icon) | Open the full settings dashboard |
| **Dynamic filtering matrix** | Granular per-site/per-type blocking (visible in advanced mode) |

### What Gets Blocked by Default

With the default configuration, uBO blocks:

- **Advertising** — banner ads, video pre-rolls, pop-ups, pop-unders, interstitials
- **Tracking** — analytics beacons, fingerprinting scripts, cross-site tracking pixels
- **Malware domains** — known phishing and malware distribution domains
- **Annoyances** — cookie consent banners, newsletter pop-ups, social media widgets (when annoyance lists are enabled)

---

## 2. Installation

### Supported Browsers

| Browser | Extension Store | Manifest Version | Notes |
|---|---|---|---|
| **Firefox** | [Mozilla Add-ons (AMO)](https://addons.mozilla.org/firefox/addon/ublock-origin/) | MV2 | Full feature support including HTML filtering |
| **Chrome / Chromium** | [Chrome Web Store](https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm) | MV2 | Requires Chrome 93.0 or later |
| **Microsoft Edge** | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/ublock-origin/odfafepnkmbhccpbejgmiehpchacaeak) | MV2 | Chromium-based, same capabilities as Chrome |
| **Opera** | [Opera Add-ons](https://addons.opera.com/extensions/details/ublock/) | MV2 | Chromium-based |
| **Thunderbird** | [Thunderbird Add-ons](https://addons.thunderbird.net/thunderbird/addon/ublock-origin/) | MV2 | Blocks trackers in HTML emails |

> [!IMPORTANT]
> **Do not install uBlock Origin from sources outside official extension stores.** Copycat extensions with similar names exist on every store and may contain malware or modified code. The legitimate extension is authored by **Raymond Hill** (gorhill). Verify the author name before installing.

> [!WARNING]
> **Chrome Manifest V3 transition**: Google is phasing out Manifest V2 extensions from Chrome. A separate extension called **uBlock Origin Lite (uBOL)** exists as a MV3 alternative with reduced capabilities. If Chrome disables the full uBO, consider switching to Firefox for the complete feature set, or install uBOL as a partial replacement.

### Installation Steps

**For all browsers:**

1. Navigate to the appropriate extension store link from the table above.
2. Click **Add to [Browser]** or **Install**.
3. Confirm the permission prompt. uBO requires:
   - Access to all websites (to inject content-blocking rules)
   - Access to browser tabs (to apply per-site settings)
   - Web request interception (to block network requests before they load)
4. The uBO icon (a shield) appears in your browser toolbar.
5. Click the icon to confirm the popup panel is working.

### Installing from Source (Development)

For testing pre-release builds:

1. Clone the repository: `git clone https://github.com/gorhill/uBlock.git`
2. In Chrome, navigate to `chrome://extensions/`
3. Enable **Developer mode** (toggle in the top-right)
4. Click **Load unpacked** and select the `uBlock/platform/chromium` directory
5. For Firefox, use `about:debugging` → **This Firefox** → **Load Temporary Add-on** and select `uBlock/platform/firefox/manifest.json`

### Post-Installation Verification

After installing, visit a test page:

1. Open any news website or ad-supported site.
2. Click the uBO popup icon.
3. Confirm the blocked request counter is greater than zero.
4. If you see `0` blocked with ads still visible, the extension may be conflicting with another ad blocker — disable other blockers first (see [Troubleshooting](#6-troubleshooting)).

### Uninstalling

Right-click the uBO icon in the toolbar → **Remove from [Browser]** → Confirm. All settings and custom filters are removed. To preserve settings before uninstalling, export them first (see [Backup & Restore](#backup--restore-settings)).

---

## 3. Configuration

### The Dashboard

Access the dashboard via:
- Click the uBO popup icon → click the **gear icon** (bottom-right)
- Or navigate directly to the extension's internal page (the URL varies by browser)

The dashboard contains seven tabs:

| Tab | Purpose |
|---|---|
| **Settings** | General preferences and behavior toggles |
| **Filter lists** | Enable/disable third-party filter lists |
| **My filters** | Write your own custom static filters |
| **My rules** | Dynamic filtering rules (advanced) |
| **Trusted sites** | Whitelist sites where uBO is completely disabled |
| **Advanced settings** | Hidden power-user settings (key-value pairs) |
| **About** | Version info and links |

### Settings Tab

The Settings tab controls uBO's core behavior:

#### Privacy Settings

| Setting | Default | What It Does |
|---|---|---|
| **Disable pre-fetching** | Off | Prevents the browser from making speculative DNS lookups and connections to sites you haven't visited |
| **Disable hyperlink auditing** | Off | Blocks `<a ping>` attributes that notify servers when you click a link |
| **Block CSP reports** | Off | Prevents your browser from sending Content Security Policy violation reports to websites |
| **Block remote fonts** | Off | Prevents loading of web fonts from third-party servers (may affect site appearance) |

#### Interface Settings

| Setting | Default | What It Does |
|---|---|---|
| **Show the number of blocked requests on the icon** | On | Displays a badge counter on the toolbar icon |
| **Make use of context menu where appropriate** | On | Adds uBO options to the browser right-click menu |
| **Disable tooltips** | Off | Hides informational tooltips in the popup panel |
| **Color-blind friendly** | Off | Adjusts the popup panel colors for accessibility |

#### Default Behavior

| Setting | Default | What It Does |
|---|---|---|
| **Enable cloud storage support** | Off | Syncs settings across browser instances via `browser.storage.sync` |
| **I am an advanced user** | Off | Reveals the dynamic filtering matrix in the popup panel |

> [!TIP]
> Enable **cloud storage support** if you use uBO on multiple computers with the same browser profile. Your filter list selections, custom rules, and whitelist synchronize automatically through the browser's built-in sync.

### Filter Lists Tab

Filter lists are the backbone of uBO's blocking. Each list contains thousands of rules maintained by the open-source community.

#### Built-in Filter List Categories

| Category | What It Targets | Key Lists |
|---|---|---|
| **uBlock filters** | uBO-specific fixes, unbreak rules, privacy | uBlock filters, uBlock filters - Badware risks, uBlock filters - Privacy, uBlock filters - Unbreak |
| **Ads** | Advertising content | EasyList |
| **Privacy** | Tracking and fingerprinting | EasyPrivacy, AdGuard Tracking Protection |
| **Malware** | Phishing and malware domains | Online Malicious URL Blocklist, Phishing URL Blocklist |
| **Multipurpose** | Combined ad + tracking | Peter Lowe's Ad and tracking server list |
| **Cookies** | Cookie consent notices | EasyList/uBO - Cookie Notices, AdGuard - Cookie Notices |
| **Social** | Social media widgets and buttons | Fanboy's Social Blocking List, AdGuard Social Media |
| **Annoyances** | Popups, notifications, overlays | Fanboy's Annoyance List, AdGuard Annoyances, uBlock filters - Annoyances |
| **Regions** | Locale-specific ads | Lists for 30+ languages/regions |

#### Managing Filter Lists

- **Enable a list**: Check the checkbox next to it
- **Disable a list**: Uncheck the checkbox
- **Update all lists**: Click **Update now** (top of the page)
- **Auto-update**: Enabled by default; uBO periodically fetches updated lists
- **Purge all caches**: Forces a fresh download of all lists on next update
- **Add a custom list**: Paste the URL of any filter list at the bottom under **Custom** → click **Import**

#### Recommended Additions Beyond Defaults

For most users, the defaults are sufficient. Consider adding:

| Goal | Enable These |
|---|---|
| Block cookie banners | EasyList/uBO - Cookie Notices |
| Block social media widgets | Fanboy's Social Blocking List |
| Block general annoyances | Fanboy's Annoyance List |
| Block region-specific ads | Your language/region list from the Regions category |

> [!NOTE]
> More filter lists does **not** always mean better blocking. Each additional list increases memory usage and filter compilation time. Lists with overlapping rules provide no extra benefit. The defaults plus one or two targeted additions cover the vast majority of use cases.

### My Filters Tab

The My Filters tab provides a full-featured code editor (CodeMirror-based) for writing your own static network and cosmetic filters.

#### Writing Static Filters

Static filters follow the EasyList / AdBlock Plus filter syntax:

```
! Block a specific URL pattern
||example.com/ads/*

! Block a domain entirely
||ads.example.com^

! Cosmetic filter — hide an element by CSS selector
example.com##.ad-banner

! Exception — allow a specific URL that would otherwise be blocked
@@||example.com/needed-script.js

! Scriptlet injection — neutralize an anti-adblock script
example.com##+js(set-constant, adBlockDetected, false)
```

#### Editor Controls

| Button | Action |
|---|---|
| **Apply changes** | Compile and activate your filters immediately |
| **Import and append** | Load filters from a file |
| **Export** | Save your filters to a file |

> [!WARNING]
> Malformed filters can break websites. If a site stops working after adding custom filters, check **My filters** first and remove or comment out (prefix with `!`) any recently added rules.

### My Rules Tab

Dynamic filtering rules provide hostname-level blocking that overrides static filters. Rules are displayed in two columns:

- **Permanent rules** (left column): Persistent rules that survive browser restarts
- **Session rules** (right column): Temporary rules for the current session only

Dynamic rules use this format:

```
source-hostname destination-hostname request-type action
```

Where action is one of: `block`, `allow`, `noop` (inherit from static filters).

Example rules:

```
* facebook.com * block
* google-analytics.com * block
example.com cdn.example.com * allow
```

#### Rule Controls

| Button | Action |
|---|---|
| **Save** | Move session rules to permanent rules |
| **Revert** | Discard session rules and reload permanent rules |
| **Import** | Load rules from a text file |
| **Export** | Save rules to a text file |

### Trusted Sites (Whitelist)

Sites listed here are completely exempt from all uBO filtering. One hostname per line:

```
example.com
accounts.google.com
*.example.org
```

Patterns support:

| Pattern | Matches |
|---|---|
| `example.com` | `example.com` and all subdomains |
| `www.example.com` | Only `www.example.com` |
| `about-hierarchical` | Special browser pages |

> [!TIP]
> Prefer using the **popup power button** to disable uBO on a per-site basis rather than manually editing the whitelist. The power button automatically adds the correct hostname entry.

### Advanced Settings

Accessible from **Settings** → **I am an advanced user** (check the box) → click the gear icon next to the checkbox. These are key-value pairs that control uBO's internal behavior.

> [!CAUTION]
> Advanced settings are intentionally undocumented in the UI. Changing values without understanding their effects can degrade performance, break filtering, or cause unexpected behavior. For a full reference of every advanced setting and its acceptable values, see the **Admin Guide**.

---

## 4. Core Usage

### Blocking Ads and Trackers (Automatic)

With default settings, uBO automatically:

1. **Intercepts all network requests** before they reach the page
2. **Evaluates each request** against the compiled filter lists
3. **Blocks matching requests** (the resource is never downloaded)
4. **Applies cosmetic filters** to hide any DOM elements that slipped through
5. **Injects scriptlets** to neutralize anti-adblock detection scripts

You do not need to take any action. Visit any website and uBO handles the rest.

### Reading the Popup Panel

Click the uBO toolbar icon to open the popup:

#### Request Statistics

The large numbers show:

```
  352         ← requests blocked on this page
  ─────
  1,204       ← total requests made by this page
```

Below the current-page stats, a smaller counter shows the **total requests blocked since install** across all sites.

#### The Power Button

The large shield/power icon in the popup serves as a per-site toggle:

- **Blue shield** = uBO is active on this site
- **Grey/faded shield** = uBO is disabled on this site

**To disable uBO on a specific site:**
1. Click the power button (it turns grey)
2. The page reloads automatically with blocking disabled
3. The site is added to your Trusted Sites list

**To re-enable:**
1. Click the power button again (it turns blue)
2. The page reloads with blocking active
3. The site is removed from your Trusted Sites list

#### Per-Site Switches (Below the Power Button)

When visible, these small toggle icons provide granular control:

| Icon | Function | Effect When Disabled |
|---|---|---|
| **No cosmetic filtering** | Disables element hiding on this site | Blocked elements may flash briefly before the page renders, or structural elements may appear blank |
| **No remote fonts** | Blocks web font loading on this site | Text renders in system fonts; may affect site appearance |
| **No large media elements** | Blocks media above a size threshold | Images, videos, and audio above the threshold are replaced with placeholders |
| **No scripting** | Disables all JavaScript on this site | The site runs in a static HTML mode; many features will break |
| **No popups** | Prevents popup windows from this site | Sites cannot open new windows or tabs |

### The Dynamic Filtering Matrix (Advanced Mode)

Enable advanced mode: **Dashboard** → **Settings** → check **I am an advanced user**.

The popup now shows a color-coded matrix grid. Each cell represents the intersection of a **hostname** (rows) and a **request type** (columns):

#### Columns (Request Types)

| Column | Type |
|---|---|
| `*` | All types combined |
| `images` | Image resources |
| `3p` | All third-party requests |
| `inline scripts` | Inline JavaScript |
| `1p scripts` | First-party script files |
| `3p scripts` | Third-party script files |
| `3p frames` | Third-party iframes |

#### Cell Colors

| Color | Meaning |
|---|---|
| **Green** | Allowed |
| **Red** | Blocked |
| **Dark green** | Allowed (overriding a block rule) |
| **Dark red** | Blocked (user-set rule) |
| **Grey** | No explicit rule (inherits from static filters) |

#### Setting Dynamic Rules

1. **Click the left half** of a cell to set a **block** rule (turns red)
2. **Click the right half** of a cell to set an **allow** rule (turns green)
3. **Click the center** to set **noop** (grey, inherit from static filters)
4. Rules set in the matrix are **session rules** by default
5. Click the **padlock icon** to make session rules permanent

> [!IMPORTANT]
> Dynamic filtering rules take precedence over static filter lists. An `allow` rule in the matrix will override a `block` rule from EasyList. This is powerful but can inadvertently disable protection if used carelessly.

### The Element Picker

The element picker lets you permanently hide specific page elements by creating cosmetic filters.

**To use:**

1. Click the uBO popup icon
2. Click the **eyedropper icon** (element picker)
3. Move your cursor over the page — elements highlight as you hover
4. **Click** the element you want to hide
5. A filter preview dialog appears at the bottom of the page showing:
   - The proposed cosmetic filter rule
   - A preview of what the page looks like with the element removed
   - A slider to adjust filter specificity (broader ↔ narrower)
6. Click **Create** to save the filter to My Filters
7. The element is hidden immediately and on all future visits

#### Element Picker Tips

- **Adjust the slider** to make the filter more or less specific. Moving toward "broad" hides similar elements across the site; moving toward "narrow" targets only the exact element.
- The generated filter is added to **My Filters** automatically. You can edit it later.
- If the picker selects the wrong element, press **Escape** and try again.
- You can also pick elements via **right-click** → **uBlock Origin** → **Block element** (if context menu integration is enabled in Settings).

### The Element Zapper

The element zapper is like the element picker but **temporary** — the element disappears until the next page load. No filter is created.

**To use:**

1. Click the uBO popup icon
2. Click the **lightning bolt icon** (element zapper)
3. Click elements to remove them — they vanish instantly
4. Press **Escape** to exit zapper mode

**Use cases:**
- Quickly dismiss an overlay blocking your view
- Remove a distracting sidebar for the current reading session
- Clean up a page before printing or taking a screenshot

### Keyboard Shortcuts

uBO registers browser keyboard shortcuts for common actions. Default bindings vary by browser and may need manual assignment:

| Command | Purpose | How to Assign |
|---|---|---|
| `launch-element-picker` | Start the element picker | Browser shortcut settings |
| `launch-element-zapper` | Start the element zapper | Browser shortcut settings |
| `launch-logger` | Open the request logger | Browser shortcut settings |
| `open-dashboard` | Open the uBO dashboard | Browser shortcut settings |
| `relax-blocking-mode` | Reduce blocking strictness on the current site | Browser shortcut settings |
| `toggle-cosmetic-filtering` | Toggle cosmetic filtering on the current site | Browser shortcut settings |
| `toggle-javascript` | Toggle JavaScript on the current site | Browser shortcut settings |

**To assign shortcuts in Chrome:**
1. Navigate to `chrome://extensions/shortcuts`
2. Find uBlock Origin in the list
3. Click the input field next to the desired command
4. Press your preferred key combination

**To assign shortcuts in Firefox:**
1. Navigate to `about:addons`
2. Click the gear icon → **Manage Extension Shortcuts**
3. Find uBlock Origin and assign keys

---

## 5. Common Tasks

### Task: Block a Specific Element on a Page

**Scenario:** A website has a floating banner or overlay that is not caught by default filters.

1. Click the uBO icon → click the **eyedropper** (element picker)
2. Hover over the unwanted element until it highlights
3. Click to select it
4. Adjust the filter specificity slider if needed
5. Click **Create**

The element is now permanently hidden on that site.

### Task: Disable uBO on a Trusted Site

**Scenario:** A banking site, internal company tool, or other trusted site is broken by content blocking.

**Quick method:**
1. Visit the site
2. Click the uBO popup icon
3. Click the **power button** (shield icon)
4. The page reloads with uBO disabled

**Precise method (for specific subdomains):**
1. Open **Dashboard** → **Trusted sites**
2. Add the hostname: `banking.example.com`
3. Click **Apply changes**

### Task: Block All Third-Party Requests on a Site

**Scenario:** You want maximum privacy on a specific site by blocking all third-party connections.

**Requires advanced mode enabled.**

1. Visit the site
2. Open the uBO popup
3. In the dynamic filtering matrix, find the `3p` column in the first row (the `*` row represents all third-party hostnames)
4. Click the **left half** of the cell to set a **block** rule
5. The page reloads — some functionality may break
6. Selectively allow specific third-party domains by clicking the **right half** of their rows as needed
7. Click the **padlock** to save the rules permanently

### Task: Block a Specific Third-Party Domain Everywhere

**Scenario:** You want to block `tracking.example.com` on every website you visit.

**Method 1 — Dynamic rule (advanced mode):**
1. Open **Dashboard** → **My rules**
2. Add: `* tracking.example.com * block`
3. Click **Save** → **Commit**

**Method 2 — Static filter (My Filters):**
1. Open **Dashboard** → **My filters**
2. Add: `||tracking.example.com^`
3. Click **Apply changes**

### Task: Allow a Specific Resource Blocked by Default

**Scenario:** uBO blocks a script or image that a site needs to function.

**Method 1 — Exception filter:**
1. Open **Dashboard** → **My filters**
2. Add an exception rule: `@@||cdn.example.com/needed-script.js`
3. Click **Apply changes**

**Method 2 — Dynamic noop rule (advanced mode):**
1. Open the uBO popup on the affected site
2. In the dynamic filtering matrix, find the blocked domain's row
3. Click the **center** of the cell to set a **noop** rule (inherits from static filters, which may allow it)
4. If still blocked, click the **right half** to set an explicit **allow**

### Task: Enable Cookie Consent Banner Blocking

**Scenario:** You are tired of clicking "Accept" on every website's cookie dialog.

1. Open **Dashboard** → **Filter lists**
2. Scroll to the **Cookie Notices** category
3. Enable **EasyList/uBO - Cookie Notices** and/or **AdGuard - Cookie Notices**
4. Click **Apply changes** (top of the page)
5. Click **Update now** to fetch the lists immediately

### Task: Block Ads in a Specific Language/Region

**Scenario:** Default English-focused lists miss ads on sites in your language.

1. Open **Dashboard** → **Filter lists**
2. Scroll to the **Regions, languages** category
3. Enable the list for your region (e.g., *EasyList Germany*, *RU AdList*, *AdGuard Japanese*, etc.)
4. Click **Apply changes**

### Task: Import Custom Filter Lists

**Scenario:** A community maintains a filter list you want to subscribe to.

1. Open **Dashboard** → **Filter lists**
2. Scroll to the bottom — find the **Custom** section
3. Check the **Import** checkbox to reveal the text area
4. Paste the URL of the filter list (one URL per line), e.g.:
   ```
   https://example.com/filters.txt
   ```
5. Click **Apply changes**

The list is fetched immediately and included in future auto-updates.

### Task: Temporarily Disable All Blocking

**Scenario:** You need to quickly test a website without any content blocking.

**Method 1 — Per-site (recommended):**
- Click the uBO popup → click the power button

**Method 2 — Global pause:**
1. Click the uBO popup
2. **Ctrl+click** (or **Cmd+click** on macOS) the power button
3. uBO is disabled globally until you click it again

**Method 3 — Keyboard shortcut:**
- Use the `relax-blocking-mode` shortcut (if assigned) to progressively reduce blocking on the current site

### Task: View What uBO Is Blocking (The Logger)

**Scenario:** A site is broken and you want to see which requests are being blocked.

1. Click the uBO popup icon → click the **list icon** (logger)
2. The logger opens in a new tab showing real-time network activity
3. Each row represents a request:

| Column | Content |
|---|---|
| **Color bar** | Red = blocked, Green/Grey = allowed |
| **Type** | Resource type (script, image, stylesheet, xhr, etc.) |
| **URL** | The requested URL |
| **Filter** | The specific filter rule that matched |

#### Logger Controls

| Control | Function |
|---|---|
| **Filter input field** | Search/filter displayed entries by keyword or regex |
| **Type buttons** | Show only specific request types |
| **DOM inspector** | Inspect the page's live DOM and see applied cosmetic filters |
| **Clear** | Clear current log entries |

#### Using the Logger to Fix a Broken Site

1. Open the logger
2. Navigate to (or reload) the broken site
3. Look for **red entries** — these are blocked requests
4. Identify which blocked request is likely causing the breakage (often a first-party script or API call)
5. Click the entry to see the exact filter rule responsible
6. Either:
   - Add an exception in **My Filters**: `@@||the-blocked-url`
   - Set a **noop** rule in the dynamic filtering matrix

### Task: Export and Import All Settings

#### Export (Backup)

1. Open **Dashboard** → **Settings**
2. Click **Backup to file**
3. Save the JSON file somewhere safe

This exports: all settings, enabled filter lists, custom filters, dynamic rules, trusted sites, and advanced settings.

#### Import (Restore)

1. Open **Dashboard** → **Settings**
2. Click **Restore from file**
3. Select a previously exported backup file
4. All settings are restored and filter lists are re-fetched

### Task: Sync Settings Across Devices

1. Open **Dashboard** → **Settings**
2. Enable **Enable cloud storage support**
3. Repeat on every browser instance where you use uBO
4. Settings sync automatically via your browser's built-in sync (requires being signed into the browser)

> [!NOTE]
> Cloud storage uses `browser.storage.sync`, which has limited capacity. Very large custom filter sets may not sync completely. The sync covers settings, enabled list selections, trusted sites, and dynamic rules. The actual filter list data is fetched independently on each browser instance.

### Task: Use uBO with Specific Content Types

#### Blocking Remote Fonts

Remote web fonts are used for both design and fingerprinting. To block them:

- **Per-site**: Click the uBO popup → click the **no remote fonts** icon (the `A` icon) under the per-site switches
- **Globally**: Open **Dashboard** → **Settings** → enable **Block remote fonts**

#### Blocking Large Media

To save bandwidth or speed up browsing on slow connections:

- **Per-site**: Click the uBO popup → click the **no large media elements** icon
- A size threshold determines what counts as "large" — elements below the threshold still load

#### Disabling JavaScript

For maximum security on untrusted sites:

- **Per-site**: Click the uBO popup → click the **no scripting** icon
- Or use the `toggle-javascript` keyboard shortcut (if assigned)

> [!WARNING]
> Disabling JavaScript breaks most modern websites. Use this only on specific sites where you want to read static content without executing any code. Many sites will show blank pages or error messages without JavaScript.

### Task: URL Parameter Stripping (removeparam)

uBO supports `removeparam` filters that strip tracking parameters from URLs (e.g., `utm_source`, `fbclid`, `gclid`). This is handled automatically by filter lists that include `removeparam` rules (such as uBlock filters - Privacy).

To add your own parameter stripping rules:

1. Open **Dashboard** → **My filters**
2. Add a rule using the `removeparam` syntax:
   ```
   *$removeparam=utm_source
   *$removeparam=utm_medium
   *$removeparam=fbclid
   ||example.com^$removeparam=tracking_id
   ```
3. Click **Apply changes**

### Task: Block or Allow Specific Request Types

Static filters support type-specific modifiers:

```
! Block all third-party scripts from a domain
||adserver.example.com^$script,third-party

! Block only images from a domain
||images.tracker.com^$image

! Allow a stylesheet that is incorrectly blocked
@@||cdn.example.com/style.css$stylesheet

! Block XMLHttpRequest (AJAX) calls to a tracker
||api.tracker.com^$xmlhttprequest
```

Available type options: `script`, `image`, `stylesheet`, `xmlhttprequest`, `sub_frame`, `font`, `media`, `websocket`, `ping`, `other`.

---

## 6. Troubleshooting

### A Website Is Broken or Not Loading Properly

**Step 1: Confirm uBO is the cause**
1. Click the uBO popup → click the **power button** to disable uBO on the site
2. Reload the page
3. If the site works with uBO disabled, proceed to Step 2
4. If the site is still broken, the problem is not uBO — check other extensions

**Step 2: Identify the problematic filter**
1. Re-enable uBO on the site (click the power button again)
2. Open the **Logger** (click the list icon in the popup)
3. Reload the broken page
4. Look for blocked first-party requests (red entries from the site's own domain)
5. Click a suspected entry to see which filter is responsible

**Step 3: Fix the issue**
- If a specific filter is breaking the site, add an exception in **My filters**:
  ```
  @@||the-blocked-resource.com/path$domain=broken-site.com
  ```
- If a dynamic rule is the cause, set a **noop** or **allow** in the matrix

**Step 4: Report the issue**
If a default filter list is causing the breakage, report it to the list maintainers or at the [uBlock Origin issue tracker](https://github.com/uBlockOrigin/uBlock-issues/issues).

### Ads Are Getting Through (Filter Not Working)

1. **Update your filter lists**: Dashboard → Filter lists → **Update now**
2. **Purge caches**: Dashboard → Filter lists → **Purge all caches** → then **Update now**
3. **Check for conflicting extensions**: Other ad blockers or privacy extensions can interfere with uBO. Disable them and test with uBO alone.
4. **Use the element picker**: If a specific ad element persists, use the element picker to create a targeted cosmetic filter for it.
5. **Check if the site uses anti-adblock**: Some sites detect ad blockers and serve ads through alternate paths. Check if uBO's anti-adblock filter lists are enabled (they are by default in the uBlock filters suite).

### uBO Uses Too Much Memory

1. **Reduce enabled filter lists**: Each list adds to memory usage. Disable lists you don't need (especially large regional lists you don't use).
2. **Enable "Ignore generic cosmetic filters"** in the Filter lists tab if you don't need cosmetic filtering for sites not explicitly covered by your lists. This significantly reduces memory on pages with complex DOMs.
3. **Check My Filters**: A very large custom filter list increases memory usage. Consolidate or remove unused rules.

### Anti-Adblock Walls ("Please Disable Your Ad Blocker")

> [!TIP]
> Before reporting anti-adblock issues, first make sure your filter lists are up to date. The uBlock filters suite and community lists are continuously updated with anti-adblock circumvention rules.

1. **Update filter lists** immediately — anti-adblock countermeasures are a constant arms race
2. **Enable additional lists** if not already active:
   - uBlock filters - Unbreak (should be on by default)
   - Adguard Base (may include anti-adblock fixes)
3. **Try a scriptlet injection filter** in My Filters:
   ```
   site-with-wall.com##+js(set-constant, adBlockDetected, false)
   site-with-wall.com##+js(abort-on-property-read, adblockDetector)
   ```
4. **Report the site** at the [uBlock Origin issue tracker](https://github.com/uBlockOrigin/uBlock-issues/issues) — the community maintains anti-adblock circumvention filters

### Extension Icon Shows No Badge / Badge Count Is Zero

1. Verify uBO is not disabled on the site (power button should show blue/active)
2. Check **Settings** → confirm **Show the number of blocked requests on the icon** is enabled
3. If using Chrome with MV3 restrictions, some blocking may occur at the declarativeNetRequest level where individual counts are not available

### Filters Not Applying After Adding Them

1. After adding filters in **My Filters**, you must click **Apply changes**
2. After enabling/disabling filter lists, you must click **Apply changes** at the top
3. **Hard-reload the page** (Ctrl+Shift+R / Cmd+Shift+R) after applying filter changes
4. Check for syntax errors — the My Filters editor highlights invalid filter syntax

### Performance Issues (Slow Page Loading)

> [!CAUTION]
> If pages load noticeably slower with uBO enabled, the issue is almost always related to too many or overly broad custom filters, not uBO's default operation. The extension is designed to make pages load **faster** by blocking resource-heavy ad and tracking content.

1. Check **My Filters** for overly broad rules (e.g., `*$script` blocks ALL scripts everywhere)
2. Check **My Rules** for rules that cause excessive re-evaluation
3. Disable recently added filter lists one at a time to isolate the cause
4. Open the Logger and check for excessive redirect loops or repeated blocked/allowed cycles

### Cloud Sync Not Working

1. Confirm cloud storage support is enabled on **all** browser instances
2. Verify you are signed into the browser's sync service
3. Check the browser's sync settings to ensure extension data is included
4. Note: `browser.storage.sync` has a storage quota (~100 KB). Very large configurations may exceed it — reduce custom filter size or dynamic rules count.

---

## 7. FAQ

### General

**Q: Is uBlock Origin the same as uBlock?**
A: No. uBlock Origin (uBO) is maintained by Raymond Hill (gorhill), the original creator. A separate project called "uBlock" (without "Origin") was forked by others and is not affiliated. Always install **uBlock Origin** specifically.

**Q: Is uBlock Origin free?**
A: Yes, completely free and open source under GPLv3. There is no paid version, no premium tier, and no monetization. It is funded purely by voluntary donations.

**Q: Does uBlock Origin sell my data?**
A: No. uBO makes zero network requests on its own except to fetch filter list updates from their publicly hosted URLs. No telemetry, no analytics, no data collection of any kind.

**Q: What is the difference between uBlock Origin and uBlock Origin Lite?**
A: uBlock Origin Lite (uBOL) is a separate Manifest V3 extension with reduced capabilities. MV3 restricts extensions from intercepting network requests in real time, so uBOL uses Chrome's declarativeNetRequest API instead. This means uBOL cannot do dynamic filtering, HTML filtering, or scriptlet injection with the same flexibility as full uBO. Use uBOL only if your browser no longer supports the full uBO.

**Q: Can I use uBlock Origin alongside other ad blockers?**
A: It is **not recommended**. Running multiple content blockers causes redundant processing, increased memory usage, and potential conflicts where one extension's exception rule undoes the other's blocking. uBO alone is sufficient — uninstall other ad blockers (Adblock Plus, AdGuard browser extension, etc.) when using uBO.

### Blocking & Filtering

**Q: Why are some ads still showing?**
A: Possible reasons: (1) Your filter lists are outdated — update them. (2) The ad is served from the same domain as the content (first-party ads are harder to block without breaking the site). (3) The ad is injected via a method not yet covered by filter lists — report it. (4) Another extension is interfering.

**Q: What is cosmetic filtering?**
A: Cosmetic filtering hides page elements using CSS rules after the page loads. Unlike network filtering (which blocks requests entirely), cosmetic filtering only hides the visual presentation of an element that has already been loaded. It is used for elements that cannot be blocked at the network level (e.g., inline ads, native ad placements).

**Q: What are scriptlet injections?**
A: Scriptlet injections are small JavaScript snippets that uBO injects into pages to neutralize anti-adblock scripts, defeat fingerprinting, or modify page behavior. They are defined in filter lists using the `##+js()` syntax. uBO includes a library of surrogate scripts for common ad/tracking libraries including Google Analytics, Google Tag Manager, Amazon ads, Chartbeat, Outbrain, Prebid, and others.

**Q: What is HTML filtering?**
A: HTML filtering modifies the page's HTML content before the browser parses it, allowing removal of inline scripts and elements that cannot be caught by network or cosmetic filtering. This feature is **Firefox only** — Chrome's extension API does not support it.

**Q: What does "removeparam" do?**
A: The `removeparam` filter type strips specified URL query parameters (like `utm_source`, `fbclid`) from requests. This removes tracking information from URLs without blocking the request itself. It is supported in network filter rules and applied automatically by filter lists that include such rules.

**Q: Can uBO block WebSocket connections?**
A: Yes. Use the `$websocket` type modifier in a filter rule:
```
||tracker.example.com^$websocket
```

### Privacy

**Q: Does uBO block browser fingerprinting?**
A: uBO blocks known fingerprinting scripts via filter lists (EasyPrivacy, uBlock filters - Privacy). However, uBO is a content blocker, not a dedicated anti-fingerprinting tool. For comprehensive fingerprint resistance, combine uBO with browser-level protections (Firefox's Enhanced Tracking Protection, or the Tor Browser).

**Q: Does uBO prevent websites from knowing I use an ad blocker?**
A: uBO includes anti-detection scriptlets that neutralize many common ad-blocker detection scripts. However, sophisticated detection methods exist that no extension can fully prevent. The community continuously updates filters to counter new detection techniques.

**Q: Are DNS requests affected by uBO?**
A: uBO blocks network requests at the browser extension level, which happens after DNS resolution. To block at the DNS level, use a DNS-based solution (Pi-hole, NextDNS, etc.) alongside uBO. However, uBO's "Disable pre-fetching" setting prevents speculative DNS lookups that leak browsing intent.

### Technical

**Q: Why does uBO need "access to all websites" permission?**
A: Content blocking requires inspecting and potentially modifying every web request and page. Without broad host permissions, uBO cannot function. The extension uses these permissions exclusively for content blocking — no data is collected or transmitted.

**Q: How often are filter lists updated?**
A: uBO checks for filter list updates automatically (default interval varies by list, typically every few days). You can force an immediate update from **Dashboard** → **Filter lists** → **Update now**.

**Q: Can I use uBO in private/incognito mode?**
A: Yes, but you must explicitly enable it:
- **Chrome**: Go to `chrome://extensions/` → find uBlock Origin → click **Details** → enable **Allow in Incognito**
- **Firefox**: Go to `about:addons` → find uBlock Origin → click **Details** → set **Run in Private Windows** to **Allow**

**Q: Does uBO work in Thunderbird?**
A: Yes. uBO can be installed in Thunderbird to block tracking pixels, remote images, and other tracking content embedded in HTML emails.

**Q: What is the `@gorhill/ubo-core` npm package?**
A: It is a programmatic Node.js module that exposes uBO's static network filtering engine for use outside the browser (e.g., in server-side applications, proxy servers, or custom tooling). It is not needed for normal browser usage. See the **Admin Guide** for details.

### Backup & Restore Settings

**Q: How do I back up my uBO configuration?**
A: **Dashboard** → **Settings** → **Backup to file**. This creates a JSON file containing all settings, enabled lists, custom filters, dynamic rules, and trusted sites.

**Q: How do I restore my configuration on a new browser/device?**
A: **Dashboard** → **Settings** → **Restore from file** → select your backup JSON file.

**Q: What format is the backup file?**
A: JSON. It contains all user-modifiable state: settings, filter list selections (not the list data itself — lists are re-fetched), custom filters, dynamic rules, trusted sites, and advanced settings.

---

_Generated May 2026 from gorhill/uBlock at afbb85c. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._