What's a Safari extension? The answer turns out to be complicated. Apple's Safari web browser first added support for extensions in version 5, and since then—we're now at Safari version 16—there have been four different extension formats!
I don't know how many people on Earth have written and released every type of Safari extension, but do I know there's at least one such person: me!
(I've also written Chrome and Firefox extensions, but let's not even go there.)
Developers like me know the technical differences between the four types of extension, but many Safari users are confused by the multitude. I hope that this blog post provides some level of clarity on the subject of Safari extensions. I'll discuss each type in turn.
Safariextz isn't really a name, it's a file extension. The original Safari extensions introduced in 2010 were distributed in an archive file format with the .safariextz file extension. In retrospect, for lack of a better name, we now call them Safariextz. Back in the day, when there was only one type of Safari extension, we just called them Safari extensions, of course.
Safariextz were the only type of Safari extension that didn't require a native app wrapper. An extension archive contained no compiled executable files, and you could develop a Safariextz without using Apple's native development IDE, Xcode. Instead, extension developers used the Safari Extension Builder, which was included in Safari itself. A Safariextz consisted of web-compatible files such as JavaScript, HTML, style sheets, and images, allowing any web developer to relatively easily create a Safari extension. Indeed, Safari extensions were very similar to, though not exactly the same as, Chrome and Firefox extensions.
Extension developers could distribute Safariextz from their own web sites, as I did, and Apple hosted the Safari Extensions Gallery (now defunct), a curated list of free extensions that was accessible from inside Safari.
I don't know why, but Apple decided to deprecate Safariextz in Safari version 12, and all support for Safariextz was removed in Safari version 13, released 2019. Safariextz is now an obsolete extension format.
Safari content blockers are the only type of Safari extension with no support for JavaScript. This is why a content blocker "does not have permission to read or transmit content from any webpages."
Notice how every type of Safari extension is combined in the Safari Extensions settings on Mac, whereas content blockers and web extensions are separated in the settings on iOS.
Safari's settings for websites allow content blockers to be enabled or disabled en masse (if you have more than one).
Instead of using JavaScript, a powerful programming language that allows developers to write arbitrary code (Turing-complete, as they say), a Safari content blocker uses a limited list of blocking rules. Each rule associates a URL pattern with an action:
http to httpsThe content blocker extension simply gives Safari a list of blocking rules, and Safari itself does all of the work, so the content blocker extension receives no information from Safari about the URLs blocked or loaded.
A lot of people think that StopTheMadness is a content blocker, but it's not. I don't blame them for being confused, because this whole blog post is about the confusion of Safari extensions. On the other hand, I do blame buyers who think that StopTheMadness is an ad blocker, even though the first paragraph of its App Store description explicitly says "StopTheMadness is not an ad blocker", and then they complain to me and in App Store reviews that it doesn't block ads… sigh. Anyway, the Safari content blocker API is too limited for the purposes of StopTheMadness, which needs JavaScript to work its magic.
Safari app extensions are exclusive to Mac, with no support for iOS. They're the only type of Safari extension that can show a native Mac user interface in Safari. Behold the massive StopTheMadness Safari toolbar popup.
(Correction: The original version of this article stated incorrectly that only Safari app extensions can add items to Safari's contextual menu. Safari web extensions can also add contextual menu items, but only on Mac, not on iOS.)
Safari app extensions can use JavaScript and style sheets, just like Safariextz, Safari web extensions, Chrome extensions, and Firefox extensions. However, the Safari app extension API is unique and significantly different from those other types of extension. This can be an advantage, because the Safari app extension API has some features that other extension API don't, but it can also be a disadvantage, because sharing extension code between different platforms is more difficult with Safari app extensions.
Safari web extensions, the newest type of Safari extension, are intended to be cross-platform. They're available on both Mac and iOS, and moreover, they've adopted the cross-platform WebExtensions API for maximum code sharing between Safari, Chrome, and Firefox extensions. Apple even has a tool for converting a web extension for Safari. Theoretically, you could use the same extension code for all of these browsers.
It's not just a walk in the (Apple) park, though. Developers looking to port their Chrome and Firefox extensions to Safari will face several major obstacles. First, Safari itself only runs on Apple devices. (Safari for Windows did exist from 2007 until 2012 but was discontinued, sadly.) Second, a number of features of the WebExtensions API are currently unsupported by Safari. Third, Safari web extensions must be distributed in the App Store, wrapped inside a native Mac or iOS app. In other words, Safari web extension developers need a Mac to run Xcode, and they need to join the $99 per year Apple Developer Program in order to distribute their Safari extension, even if the extension is free. (Fee waivers are granted only to certain well-documented, bureaucratic nonprofit institutions.)
Safari web extensions use a special permissions system that grants them access to specific websites. When you first enable a Safari web extension, it doesn't have access to any websites.
You can allow access from the Safari Websites settings.
Or you can allow access directly from the extension's Safari toolbar icon.
The same system exists on iOS.
In contrast, Safari app extensions don't use this newer website permissions system. They're all or nothing. When you enable a Safari app extension, it immediately has access to all of the websites specified by the extension. Safari gives scary warnings both before you enable an app extension and when you try to enable an app extension.
Unfortunately, there's nothing that Safari app extension developers can do about the situation. I've filed Feedback with Apple to allow Safari app extensions to use the same permissions system as Safari web extensions.
If you'd like more information about what those scary warnings mean, I wrote a blog post about them a few years ago. In essence, what they mean is that the extension can run JavaScript on the web page. This is necessary for extensions to function. As a consequence, though, it gives extensions access to everything on the page. You definitely need to choose your Safari extensions carefully. Look for a trustworthy developer, like, for example, me!
As an extension user, how can you tell the difference between the four types of Safari extensions? On iOS, it's relatively easy: in Safari Extensions settings, if the extension is listed under ALLOW THESE CONTENT BLOCKERS, then it's a content blocker, and if it's under ALLOW THESE EXTENSIONS, then it's a Safari web extension. On Mac, you have to go by various clues:
This last point deserves discussion. There's a widespread misconception that Safari extensions on the Mac can only be distributed via the Mac App Store, and while this is true of Safari web extensions—one of the few Mac API that for some strange reason are limited to the App Store—it's not true of Safari app extensions. See for example the Subscribe to Feed extension in the first screenshot above. This extension is bundled with the NetNewsWire app distributed outside the Mac App Store. I don't think it's true of Safari content blockers either. Although I'm not aware of any content blockers that are distributed on the Mac outside the Mac App Store, my testing indicates that Safari recognizes and uses a Safari content blocker signed with a Developer ID certificate.
Speaking of strange reasons, App Store app requires you to quit Safari in order to install Safari app extension updates.
This requirement doesn't exist for Safari web extensions or Safari content blockers. I don't know why it exists for Safari app extensions, but it's painful to me as a Safari app extension developer, because my customers don't like to be forced to quit Safari. Once again, I've filed Feedback with Apple to eliminate the requirement.
Due to the strict limits of their API, Safari content blockers are inferior to Chrome and Firefox extensions such as uBlock Origin at blocking ads and other annoyances. When support was introduced for Safari web extensions, people were excited about the prospect of uBlock Origin returning to Safari. There was previously a Safariextz version of uBlock Origin that of course died when Safariextz did. The hopes for a rebirth were in vain, unfortunately, for as I mentioned earlier, a number of features of the WebExtensions API are currently unsupported by Safari. One crucial feature for uBlock Origin is webRequest BlockingResponse, without which it doesn't really matter whether Safari supports other WebExtensions API. uBlock Origin still can't be ported from Chrome or Firefox to Safari.
Chrome extension manifest version 3 has been accused of hindering ad blockers. Ironically, the new ad blocking API in manifest V3, declarativeNetRequest, seems to be modeled after the Safari content blocker API. They both use strict, limited, predefined lists of rules instead of flexible JavaScript. In a sense, Safari did it first! Yet as a result of Chrome's market share dominance on desktop, mostly due to the nonexistence of Safari on Windows, Chrome manifest V3 has received most of the bad publicity with regard to ad blocking. (Mobile Safari never had Safariextz or uBlock Origin, so Safari content blockers were actually the first ad blockers on iOS.)
By the way, both Safari and Firefox now have support for Chrome manifest V3—including the newer declarativeNetRequest content blocking API—albeit not full support. To be fair, Chrome doesn't have full support for manifest V3 either! Google has announced and postponed the removal of manifest V2 support from Chrome multiple times. They keep kicking the can down the road, because manifest V3 isn't ready yet. The latest news is that it won't happen until 2024 at earliest. Regardless, the good news is that neither Safari nor Firefox have announced a plan to remove manifest V2 support. My impression is that both browsers intend to continue to support manifest V2 after Chrome removes it. I'm sure that won't last forever, but it's likely to last longer in Safari and Firefox than in Chrome. Google is the driving force behind manifest V3, and the other browsers only want to maintain cross-platform extension compatibility. Again, though, Safari is the only web browser that has already removed all support for JavaScript-based content blocking, which it did back in 2019 when Safariextz were eliminated.
I'm bad at writing conclusions, so I won't. I just hope that this blog post has helped somewhat to clarify the complexity surrounding Safari extensions. My ulterior motive was to use this as a reference that I can point my customers toward when they have questions or experience confusion.