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.
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.
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).
The 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.
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 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.
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.
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.