What's happening with Safari extensions?

Apple is phasing out old-style Safari extensions with the release of MacOS 10.14 (Mojave) this fall. By December, no new extensions or updates to existing extensions will be accepted in the Safari Extensions Gallery. Instead, Safari extensions will be bundled with Mac apps installed and updated from the App Store.


Apple is also retiring one of the two APIs developers have used to block ads in Safari. (What is an API, for people who aren't nerds.) The one that's left, the Content Blocking API, has some important differences that forced us to rewrite large parts of our Safari extension from the ground up. The good news is that we had a head start. AdBlock has included Content Blocking as an optional setting since the release of Safari 9 in 2015. With the September update, we have removed the retired API entirely. As a result, AdBlock works differently and some of your settings may have changed.


We've listed the major changes below, and we've also included answers to common questions at the bottom of this article. 


What has changed?

Here's a quick overview of what has changed in the AdBlock for Safari extension that is available in the Gallery. (Here are the technical details.)


The Pause feature is no longer available

To temporarily allow ads to appear (for example, to view content on a site that bars ad blockers), you now need to disable AdBlock in Safari Extensions Preferences and remember to re-enable it when you leave the site. Selecting Pause AdBlock in the AdBlock menu now shows you a reminder of the new procedure.


This means that to temporarily turn off ad blocking, open Safari > Preferences > Extensions and uncheck AdBlock in the left column. To resume blocking ads, select AdBlock.


To "pause" and "unpause" AdBlock after the September update, disable and re-enable AdBlock in Safari > Preferences > Extensions.


Tip:
To quickly open Safari > Preferences, press Cmd+, (the Command and comma keys together). The Safari Preferences window opens with your last selected preference active. So after the first time you open Safari Extensions Preferences, pressing Cmd+, is a quick shortcut to pausing and unpausing AdBlock.


You may need to unsubscribe from some filter lists

The Content Blocking API sets an upper limit of 50,000 on the number of filter rules Safari can process in one pass. If you see the following notice in Safari:

Please disable some filter lists. More information in AdBlock's Options.


it means that the total number of filter rules in all the filter lists you are subscribed to has exceeded the limit. (What filter lists are, for people who use ad blockers.)


What happens if my filter lists put me over the limit?

Strictly speaking, you can ignore the notice if you want to. AdBlock collects all the rules in the filter lists you are subscribed to, dumps them into a file, and sorts them before sending the file to Safari. Hiding rules come first, then blocking rules, then whitelist rules. Any rules in excess of 49,999 are simply discarded. The sorting ensures that most of the blocking and hiding rules will probably make it to Safari.


This is highly dependent on which filter lists you have enabled, however. A large filter list like EasyList can easily consume most of that allowance. We want to make sure that you, not AdBlock's truncating algorithm, stay in control of your browsing experience. The notice is our way of recommending that you review your filter list subscriptions and decide whether there are any you can do without to stay under the limit.


Some of your custom filters may stop working

Not all filter rules are compatible with the syntax required by the Content Blocking API. AdBlock tries to convert any custom filters it finds, but the process is not foolproof. Some custom filters may no longer work, or may even break a site. If a site for which you have a custom filter starts to behave badly, remove the custom filter and reload the misbehaving page.


You must add your own whitelist filters to allow ads on websites you want to support

We have removed Don't run on pages on this domain from the AdBlock menu. You can still allow ads on an entire site by adding a custom whitelist filter yourself on the CUSTOMIZE tab in AdBlock's options.

  1. Click the AdBlock icon in the browser toolbar and select Options.
  2. On the CUSTOMIZE tab, click Edit.
  3. In the text box, type a custom filter in the following format, replacing "example.com" with the site's domain name: @@||example.com/$document


Your web page and YouTube channel whitelist filters now whitelist the parent site

Content Blocking doesn't allow whitelisting (allowing ads on) individual web pages and YouTube channels. We have removed Don't run on this page from the AdBlock menu and Allow whitelisting of specific YouTube channels from AdBlock's options.


There is an important consequence of this that we want you to be aware of. Custom filters that whitelist an entire site haven't changed. But if you had any filters that whitelisted an individual web page or YouTube channel before the update, we converted them to whitelist the domain the page is part of. This means that if you had whitelisted even one YouTube channel, ads can now appear anywhere on YouTube.com.


Some Facebook ads may not be blocked

The Content Blocking API blocks more kinds of ads on more sites than the old, retired method, including ads in Flash videos and games. It doesn't block Facebook ads and sponsored posts as efficiently, however.


Content Blocking is no longer optional

We have removed Use Safari Content Blocking from AdBlock's options.


How will these changes affect me?

If you spend most of your browsing time on Facebook, you may see more ads and sponsored posts.


If you often visit websites that ask you to disable your ad blocker, the Cmd+, (Command and comma) key combination will become your new best friend.


If you like to support websites by allowing their ads to appear, you need to add the appropriate whitelist filter to AdBlock yourself.


If you are a "power user" with lots of filter list subscriptions and custom filters, you may need to manage your subscriptions differently and debug (or remove) some of your filter rules.


Why did you break AdBlock? It was working fine!

We aren't happy about some of the compromises we had to make, either. Like all extension developers, we are at the mercy of the platforms we support. Apple is making sweeping changes to how Safari extensions are built and distributed. Our choice was to let Apple remove AdBlock from the Extensions Gallery and the browsers of millions of our Safari users, or adapt and work as hard as we can to keep your AdBlock experience the best it can be. It wasn't a difficult choice. :)


Why didn't you ask me before you made all these changes?

We wish we could have. We didn't for two reasons: We had a very short deadline to get a version of AdBlock into the Extensions Gallery that complies with Apple's new order. And we really didn't have any choice about the changes we had to make to be in compliance. Our message to you would have been basically, "You can have any color you want as long as it's black."


I'm not happy with the new AdBlock extension. What are my options?

If you don't like these changes, you have other options.


Install the new AdBlock for Safari app

The best option is to switch to our brand-new Mac app. Safari extensions and the Safari Extensions Gallery are going the way of the dinosaurs in a few months. When that happens, the app will be the only AdBlock available to Safari users who have upgraded to MacOS Mojave.


The AdBlock for Safari app is a work in progress. Converting our old Safari extension to the new Safari App Extensions platform and Content Blocking API is complicated, for a variety of technical reasons we won't get into. We are porting over features from the extension as quickly as we can. Need help deciding whether to use the app or the extension?


Install our self-hosted extension

If the Mac app doesn't yet have a feature you need, you can install the self-hosted version of AdBlock instead. Only ad blockers that want to stay in the Safari Extensions Gallery have to use the Content Blocking API exclusively. The version that we host on our website still uses the old API, and Content Blocking is still optional.


We may decide to stop adding new features to the self-hosted extension at some point. If we do, we will notify you so that you can switch to the AdBlock app if you like. (You may need to update to the latest version of Safari first.)


Note: If you have upgraded your Mac to MacOS 10.14 (Mojave), you cannot install self-hosted extensions.


Use a different browser

Safari is a good browser, with features not found in other modern browsers. If you're a die-hard Apple fan, using products that are all in the Apple ecosystem has some advantages. On the other hand, AdBlock for Chrome and Firefox have features and advantages we aren't able to offer our Safari users in either version of our extension or the new app.


   
AdBlock for Safari
(Gallery)
AdBlock for Safari
(self-hosted)
AdBlock for Safari
(App Store)
AdBlock for Chrome
AdBlock for Firefox
Content Blocking API
Yes
Optional in Safari 9+Yes
No
No
Pause AdBlock
No
Yes (everywhere)
Yes (everywhere)
Yes (current site and everywhere)
Yes (everywhere)
Page whitelisting
No
Yes
Yes
Yes
Yes
YouTube channel whitelisting
No
Yes
No
Yes
Yes
Site whitelist wizard
No
Yes
No
Yes
Yes
Auto-whitelist subscribed YouTube channels
No
No
No
No
Yes
50,000 filter rules maximum
Yes
No
Yes
No
No
Subscribe to optional filter lists
Yes
Yes
No
Yes
Yes
Subscribe to additional filter lists by URL
Yes
Yes
No
Yes
Yes
Blocks ads on Facebook
Some
All
Some
All
All
Blocks Flash ads
Yes
No
Yes
Yes
Yes


Related articles

Is it true AdBlock will stop working when I upgrade to Safari 12?

"Safari no longer supports the unsafe extension AdBlock"

What is Safari Content Blocking?

Why do I see two AdBlock buttons in Safari and three AdBlocks in Safari Extensions Preferences?

Getting started with the AdBlock for Safari app

Frequently asked questions about the AdBlock for Safari app