Running your Safari web extension
Install and update your extension in Safari as you make changes in development.
Overview
Install your web extension in Safari, then update it as you add features and fix bugs so you can run and test it in Safari.
You can temporarily install your extension folder in macOS Safari for testing without setting up an Xcode project. Use this approach to quickly evaluate your extension in Safari or to complete your initial development work. Then, when you’re ready to test your extension in iOS or distribute your extension, follow the instructions in Packaging a web extension for Safari to create an Xcode project.
Temporarily install a web extension folder in macOS Safari
To temporarily install your web extension folder in macOS Safari, first locate the folder or zip file containing your web extension’s files in Finder, then open Safari.
In the Safari menu, choose Safari > Settings.
Select the Developer tab. If it’s not visible, see Configure Safari in macOS to run unsigned extensions below to enable it.
Click “Add Temporary Extension…”, then respond to Safari’s unsigned extension authentication prompt, if you haven’t already selected the “Allow unsigned extensions” option.
Select the folder or zip file containing your web extension files, and click Select.
If your folder contains a valid web extension, Safari switches to the Extensions tab and adds your extension to the Temporary list. Use the options to uninstall the extension, adjust the extension’s settings, show the extension in Finder, or reload the extension in Safari.
Safari removes temporary extensions after 24 hours or when you quit Safari.
Install your Safari web extension in iOS
If you’re working in iOS, you deploy a Safari web extension in Safari with an iOS app. If you are testing on a device, attach your development iOS device to your computer, then run the containing iOS app to install your web extension in Safari:
Select the iOS app in the Scheme menu next to the Run and Stop buttons in Xcode’s main toolbar.
Select your development device or preferred iOS simulator in the Device menu next to the Scheme menu.
Click the Run button, or choose Product > Run to build and run your app.
Xcode builds your Safari web extension first, then embeds it inside the finished app bundle. Xcode then deploys the app to your development device or selected simulator.
When you install the app in iOS for the first time, enable the web extension in Safari before you run it. In Safari, tap the More menu, then tap Extensions to select and enable your extension. Alternatively, open the Settings app, then select Safari > Extensions. Find your extension in the list, tap it, then tap the switch to enable the extension.
Install your Safari web extension in macOS
If you’re working in macOS, you use a macOS app to deploy a Safari web extension. Run the containing macOS app to install your web extension in Safari:
Select the macOS app in the Scheme menu next to the Run and Stop buttons in Xcode’s main toolbar.
Click the Run button, or choose Product > Run to build and run your app.
When you build your app, Xcode builds your Safari web extension first, then embeds it inside the finished app bundle. As soon as your app runs, your extension is ready for use in Safari.
Configure Safari in macOS to run unsigned extensions
If you’re not part of the Apple Developer Program, or if you haven’t yet configured a developer identity for your existing Xcode project, your Safari web extension won’t be signed with a development certificate. For security purposes, Safari ignores unsigned extensions by default, so your extension won’t show up in Safari Extensions preferences.
To develop without a certificate, allow unsigned extensions in Safari. First, enable the Develop menu in Safari:
Choose Safari > Settings.
Select the Advanced tab.
Check the “Show Develop menu in menu bar” box, or the “Show features for web developers” box in Safari 17 or later.
Then, in Safari 16 and earlier, choose Develop > Allow Unsigned Extensions. In Safari 17 or later, use the Developer tab in Settings:
Choose Safari > Settings.
Select the Developer tab.
Check the “Allow unsigned extensions” box.
The “Allow unsigned extensions” setting for Safari resets when you quit Safari; set it again the next time you launch Safari.
In a Mac web app:
Choose Settings from the Mac web app’s menu.
Select the Extensions tab.
Check the “Allow unsigned extensions” box.
The “Allow unsigned extensions” setting resets for the web app when you quit that web app; set it again the next time you launch the web app.
Now enable your extension:
Choose Safari > Settings, or Settings from the Mac web app’s menu.
Select the Extensions tab. This tab shows the localized description, display name, and version number for the selected extension. It also provides more information about the permissions claimed by the extension.
Find your new extension in the list on the left, and enable it by selecting the checkbox.
Close Settings.
If you have profiles set up in Safari 17 or later, manage your extension for a specific profile:
Choose Safari > Settings.
Select the Profiles tab.
Select a profile.
Select the Extensions tab.
If you built the default template extension without modifying it, Safari adds a button in the toolbar after you complete the steps above. When you click this button, Safari displays the pop-up webpage from your web extension.
If you have trouble getting your extension to work, see Troubleshooting your Safari web extension.
Update your Safari web extension in iOS
To deploy changes to your extension after installing it the first time, choose Product > Run. Xcode packages the most recent changes to your extension files in the iOS app. As soon as the build completes and Xcode installs the app on your device or selected simulator, your extension updates are ready to use in Safari.
Update your Safari web extension in macOS
To deploy changes to your extension after installing it the first time, choose Product > Build. Xcode packages the most recent changes to your extension files in the macOS app. As soon as the build completes, your extension updates are ready to use in Safari.