The Ultimate Superuser’s Guide to uBlock Origin

uBlock Origin is the most powerful and versatile ad blocker available. Unfortunately, the design is also a little obscure. This guide will explain the ins and outs of uBlock Origin’s advanced features, including adding custom lists, creating custom user filters, setting up dynamic blocking rules, and adjusting rules for uBlock Origin on specific domains with the advanced user interface.

Installing uBlock Origin

A pre-built version of the uBlock Origin extension is available for Google Chrome, Firefox, Safari, Microsoft Edge and Opera. You can also build the extension manually from source for Firefox and Chrome.

A quick warning: uBlock Origin is not and has never been connected to ublock.org or the uBlock extension. The Origin part in the name is very important in distinguishing between these two unrelated projects that once shared a similar codebase. ublock.org and the uBlock extension should be avoided, as they are imitators that purposefully confuse the market to steal data and deceive users. Be sure you have uBlock Origin and not uBlock.

Setting Up Advanced Options

Before we can do anything interesting with uBlock Origin, we need to enable advanced settings. Make sure to check out the required reading before you proceed. If you lack the troubleshooting experience to manage these types of decisions, consider reading up on how cookies work before you start tinkering with their functionality. Otherwise, expect the unexpected!

1. Click on the uBlock Origin extension’s icon.

2. Click the Settings icon.

ublock-origin-click-settings-icon

3. Tick the box next to “I am an advanced user.”

ublock-origin-advanced-user-checkbox

Once you have advanced settings enabled, you can adjust blocking settings on a granular level.

Dynamic Filtering Rules

Filtering is handled in uBlock Origin at two levels: globally and locally. Global rules apply to all URLs, while local rules are for the current URL only.

The first column specifies the URL that the content originates from.

ublock-origin-url-resource-origin-column

The second column indicates global settings, which are inherited by the specific URLs.

ublock-origin-global-rules-column

The third column indicates local rules for the current URL.

ublock-origin-local-rules-column

If you mouse over a box in the “global” or “local” rules column, you’ll see red, grey, and green thirds.

ublock-origin-rules-colored-column

Click on the red third to set a blocking rule for the associated content type. The green third permits the corresponding element. The grey third sets a “noop” rule, which stands for “no operation.” This setting will prevent uBlock Origin from taking action on the associated content. Setting a “noop” filter will override global settings for a specific URL.

At the top of the window are content types. These can be blocked at the global and URL-specific level. These are blunt filters but useful nonetheless.

Under the content types are the URLs loaded on the current webpage. A plus icon indicates that content from that URL is being permitted. A minus icon indicates that content from the URL is being blocked. You can sometimes see a mixture of pluses and minuses for one URL, which indicates that some of the content is permitted while other content is blocked.

You can also look at the color coding next to the URL. Green indicates that content from that URL is permitted. Yellow indicates that some content from that URL is blocked. Red indicates that all content from the URL will be blocked.

Settings an inherited based on specificity. For example, global content type rules have the lowest priority. Rules set on filtering lists have a medium priority ranking: they can override global settings, but not URL-specific user settings. The highest priority is given to URL-specific local rules set by the user.

Saving and Reverting Filtering Rules

Changes you make to filtering rules are automatically reset the next time you visit a website. To make your settings permanent, click the lock icon.

ublock-origin-make-changes-permanant

To revert to the last saved state, click the eraser icon.

ublock-origin-reset-current-changes

Third-Party Scripts and Frames

In general, it’s a good idea to block third-party scripts and frames by default. This protects both your privacy and your eyeballs. It can also break websites, so keep a quick finger on the “noop” override.

To block third-party scripts and frames, click the red third of the box next to each in the global column. This will automatically block all third-party scripts and frames on every URL.

ublock-origin-set-global-blocking-rule

If a website breaks, you can set a “noop” override to permit third-party scripts and frames. Click the grey box in the local rules column to set a “noop” rule and override the global blocking rule for this URL.

ublock-origin-noop-override-local-filter

This noop rule will only apply to the current URL.

Alternatively, you can also hunt down the URL of the blocked resource and permit that resource specifically. This is easiest with the third-party frame has a clear origin, like a YouTube or Twitter embed. If you permit those frames globally and save the rule, those URL-specific filters will trump the global content type filters.

By balancing global and local filters with content type filters, you can set sensible online privacy settings while permitting content you don’t find as objectionable.

Viewing and Editing Dynamic Rules

To view the filters that you’ve already set, look at uBlock Origin’s Settings page under the My Rules tab. Here, you’ll see the rules you’ve set in two lists. The list on the left is for permanent rules and the list on the right is for temporary rules, as indicated by their headings.

ublock-origin-dynamic-filtering-rules-list

The text contents of the right-most temporary rule column can be edited directly with the cursor, mouse, and keyboard. If uBlock Origin detects a difference between the two columns, you’ll see contextual buttons labeled “Revert” and “Commit” that offer the option to sync the columns with one another. Click “Revert” to copy the unchanged contents of the permanent rule list to the temporary rules list. Click “Commit” to copy the change from the temporary rules list to the permanent rules list.

You’ll notice that the text formatting of the rules follows specific conventions. The syntax is like so:

If you follow the dynamic filtering rules syntax guide on uBlock Origin’s GitHub page, you can change and set rules with text strings directly from this pane.

Removing Elements with Static Rules

If you want to remove elements from the page using graphical tools, you can access that feature by setting cosmetic rules. These rules remove DOM elements based on a graphically-based node selection by the user. If you see something on a website that bothers you, like a email subscription banner, an ad-block detector, or anything else offensive to your sensibilities, you can remove it this way.

Temporary Rules: Element Zapper

There are two different ways to set cosmetic rules in uBlock Origin. The first is with the Element Zapper, accessed through the lightning bolt icon on uBlock Origin’s extension dropdown pane.

ublock-origin-create-element-zapper-rule

This tool sets a temporary rule removing the specified DOM element. With the next browser session, the element will return. To create a rule, click the element zapper icon, and then click on the page element you want to remove. As you mouse over various DOM elements, they’ll be colored yellow to indicate what element is currently selected. Once the right element is selected, click to remove the selected element instantly. No confirmation box will appear after clicking

ublock-origin-create-element-zapper-selection

The element zapper will do its best to pick the element you’ve selected, but you might need to dance your mouse around a bit to get the element you’re hoping for. It will attempt to adhere to the largest DOM object that its algorithm can locate and select.

Permanent Rules: Element Picker

To set a permanent rule, use the Element Picker, represented by the eyedropper icon to the right of the lightning bolt.

ublock-origin-create-element-picker-rule

This will activate an interface similar to the element zapper, but now DOM elements will be highlighted in red instead of yellow.

ublock-origin-create-element-picker-selection-1

When you click on the red highlighted element, a text box will appear in the lower-right, previewing the class or ID of the selected element. It’s this text-based class or ID match that will be used to remove the element in the future. And since many sites obfuscate their code to make ad blocking more difficult, you may need to refine the element picker’s automatic selection from time to time. You can also use this tool to select “layers” of the DOM that are completely obscured or exist only in DOM logic.

ublock-origin-create-element-picker-selection-2

To select a different element, mouse over its name in the yellow box below the white text box. Click on the text to see the associated element highlighted in red.

ublock-origin-create-element-picker-selection-3

When the correct element is selected, click the “Create” button to create the rule and remove the element. You can also click the adjacent “Pick” button to return to the element picker if you selected the wrong part of the page.

ublock-origin-create-element-picker-selection-4

In the future you can find the rule in uBlock Origin’s settings under the “My Filters” tab. New rules will appear at the bottom of the list with their data and timestamp.

ublock-origin-create-element-picker-selection-5

If you want to ignore a rule, you can type an exclamation point at the beginning of the line to comment out the element rule. You can also see additional static filer syntax in uBlock Origin’s documentation on GitHub.

Finding and Using Custom Filter Lists

uBlock Origin comes with some preset filter lists, but there are many more you can add. The easiest way to add more filters is to browse FilterLists.

If you find a filter list you want to add to uBlock Origin’s filters, click “Details” and then “Subscribe.” This will automatically download and include the list in uBlock Origin’s blocking rules for websites visited in the future. Only lists with the uBlock Origin icon can be added to uBlock Origin in this way.

ublock-origin-add-custom-filters

These filters will then appear under the “Filter Lists” tab in uBlock Origin’s options page. They can be viewed and toggled from that page in the future.

ublock-origin-custom-filter-list-settings

Storing and Syncing Rules

To make a local backup of your uBlock Origin rules, you can save your settings out to a file. Find the dialog options at the bottom of the main uBlock Origin settings tab.

ublock-origin-back-up-to-file

If you want to use the browser-based cloud storage for extensions, you can tick the “Enable cloud storage” option on the main page of uBlock Origin’s settings. This will allow you to upload data within the extension’s small file space within the browser. This only syncs with other copies of the same browser, however.

ublock-origin-enable-cloud-sync

If you upload your uBlock Origin settings in Firefox, you cannot then download them in Chrome on another computer. As a result, sharing configurations through files is the most reliable method of the time being. To sync your rules among multiple browsers and computers, you can share the backup configuration text file over a cloud storage service.

Conclusion

uBlock Origin isn’t exactly an ad blocker. It’s a wide-spectrum content blocker. That means it can control what comes into your browser no matter its origin. That makes it extremely powerful, and extremely easy to mess up. So take care with what you do, and if something breaks, be prepared to fix it.

8 comments

  1. Thanks. Just what I needed to fine-tune my uBlock Origin.

  2. Need to carefully reread this post. I gave up on uBlock Origin (it seemed difficult to manage intuitively) and installed another ad-blocker that uses the same set of lists. I do like the author’s uMatrix extension – which I use extensively and so much easier to manage, control and tweak.

    Would love it is he uses the same interface on uBO as he does on uMatrix. I’ll give uBO a dry run again since I figure it and uMatrix are built to work well together (with some minor overlap).

  3. To save or revert Filtering Rules automatically:
    Ctrl+clic on a cell, no need to use the lock icon anymore.

  4. ublock origin is an ad blocker.

    1. @Carter – uBlock Origin is a general purpose blocker that can block ads. If you think of uBlock Origin as an ad blocker you misunderstand its purpose and are missing out on the core of its functionality.

      https://github.com/gorhill/uBlock/wiki/Blocking-mode
      https://github.com/gorhill/uBlock#philosophy

  5. In what scenario would you use a “noop” rule over an “allow” rule?

    1. * noop rule means uBo will not block it dynamically. But if the domain is in a filterlist ie. EasyList or EasyPrivacy then the URL will be blocked. * allow will override the filterlist & potentially allow a ad URl or malicious URL.

    2. @Thomas

      Here’s a specific example.

      Scenario 1:

      1. You create a global dynamic rule to block all 3rd party scripts. So anytime you visit a site, all scripts that aren’t loaded from the same site will not be able to run.

      2. You visit some site frequently and it requires certain 3rd party scripts to work properly.

      3. You create a local dynamic **ALLOW** rule for 3rd party scripts. This overrides the global dynamic rule from step 1, as well as all static filters. **ALL** scripts now work — the scripts needed for the site to work properly, AND the tracking scripts used to profile you and follow you around the internet.

      Scenario 2:

      1. You create a global dynamic rule to block all 3rd party scripts. So anytime you visit a site, all scripts that aren’t loaded from the same site will not be able to run.

      2. You visit some site frequently and it requires certain 3rd party scripts to work properly.

      3. You create a local dynamic **NOOP** rule for 3rd party scripts. This overrides the dynamic global rule from step 1, but it is not an _allow_ rule so it does _not_ override static filters. Scripts that are presumed to be safe will run, most likely the site works properly now. The tracking scripts however are going to be blocked by the static filters that identify parts of their URL, such as “/adsense/”, which could come from any of a number of domains.

      Results:

      Scenario 1 fixes the site but leaves you wide open to any and all scripts the page tries to run. Scenario 2 most likely fixes the site, but still blocks the undesirable scripts that can be a threat to your security and privacy. It’s possible there are still other pieces that will need to be changed for the site to display completely as intended, depending on your settings, such as allowing fonts on the site. The scripts required for site functionality should all be working now though.

Leave a Comment

Yeah! You've decided to leave a comment. That's fantastic! Check out our comment policy here. Let's have a personal and meaningful conversation.