Userscripts Safari: App Store only since 4.x, and an iOS app that cannot tell whether its own extension is enabled
An open-source userscript manager for Safari
At a glance
- What is it?
- Userscripts is quoid's GPLv3 userscript editor for Safari, shipped as an App Store app for iOS and macOS and still in a 5.0.0 beta line. Its build scripts target Safari 15 and Safari 16.4 separately for macOS and iOS, its iOS half has no script editor at all, and the iOS app reports nothing about whether the extension is actually enabled in Safari.
- Who is it for?
- Userscripts fits a Safari-only workflow where you want a script editor in the browser rather than a library of preinstalled scripts, and it does not fit anyone cross-browser, since the whole project is Safari specific. Four things to check before you rely on it.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- quoid/userscripts4,914 ★ · +129
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| quoid/userscripts | 4.8k | 4.9k |
129 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Direct downloads ended because of how Apple distributes WebExtension apps
Installation is one route only, and the history behind it explains a limitation. Userscripts is available for iOS and iPadOS and for macOS, and for all versions installation goes through Apple's App Store. On macOS, versions prior to 4.x were available to download and install directly from the repository, and that option no longer exists because of changes in the way Apple allows developers to distribute apps built with the WebExtension API, tracked as issue 154. The platform floors are stated precisely: iOS 15.1 or higher, and on macOS you should be running macOS 12 or higher along with Safari 14.1 or higher. The repository also carries separate build targets for Safari 15 and Safari 16.4.
The iOS app sets a directory and cannot report whether its extension is on
The iOS half of the app has a narrower job than the macOS half, and the reason is a limitation the README states plainly. After installing, you take two main steps: open the app and set a directory for saving and loading userscripts, and enable the extension in Safari while granting permissions. Versions after 1.5.0 set a local default directory automatically; earlier versions required clicking the Set Userscripts Directory button. Extensions are managed from the Settings app under Safari and Extensions, or from Safari itself using the AA button on iPhone and the extension icon on iPad, which is also where you open the extension popup. Then the caveat: the iOS app cannot detect whether you have enabled the extension in Safari, so the app prompt will not change after you enable it. Currently the app interface is only used to set or change the userscripts directory. For a recommended experience the documentation suggests Always Allow for All Websites, which is a permission decision to make deliberately rather than a default to inherit.
There are two ways to add a script, and the URL must end in .user.js in the path
On iOS you can add a script in either of two ways. Visit a .user.js URL in Safari, then open the extension popup and you will see an installation prompt, with the constraint that the URL should end with .user.js in the path part rather than the query or hash parts. Or save files with the .user.js extension directly into the userscripts directory you set. Both work equally well on macOS. The iOS version does not include the script editor that the macOS version has, which is the single biggest functional difference between the platforms. The suggested workaround is to edit the script files in the directory directly on iOS using any third party code editor app, since those support in place opening and editing. Note that the same directory is used on both platforms, so a script written on a Mac and synced to an iPhone can be edited there even though no editor is built in.
iCloud sync can evict your scripts, and the fix is a folder setting
The syncing story has a documented failure mode with a documented workaround. You could select an iCloud folder for syncing scripts between macOS and iOS, and the caveat is that there may be delays in synchronization and you may encounter files being evicted due to iCloud optimization, tracked as issue 424. The instruction, effective since macOS 15 and iOS 18, is to set keep downloaded for the folder to avoid the eviction. That is a real operational dependency on platform behaviour outside the project, and it is worth knowing before you keep your only copy of a script in iCloud. For the non-syncing case the default directory is the one the app chooses automatically, described as ~/User/Library/Containers/Userscripts/Data/Documents/scripts. On macOS you do not need to select a directory at all if you are not syncing across devices, and you should only pick another location if you want your scripts elsewhere, which the documentation notes is especially useful if you edit with an external tool such as Sublime Text or VSCode.
Updates only fire when the metadata carries both @version and @updateURL
The update button in the editor is not a general fetch, and the conditions it imposes are listed rather than buried. It allows you to update userscripts that meet two requirements: the metadata contains an @version tag, and the metadata contains an @updateURL tag. A script missing either will not update no matter how old it is. The download button next to it has a different purpose that is easy to misread, so the note explains it: every userscript displayed in the interface is already present on your local machine at your save location, and the download button offers a quick way to retrieve a copy of that file without going through the settings button and then the save location link inside the settings modal. The third button, the trash button, moves the currently loaded userscript to the trash bin, after which it is removed from the interface and from the save location. So the three buttons are update from remote, copy from local, and delete from local.
The sidebar offers CSS, JavaScript and remote, and they are the same kind of object
The plus button in the sidebar adds a new item, and the three choices are worth reading carefully because they define what the extension considers a script. New CSS is described as a userscript that expects CSS code, so styles live in the same list as scripts and are managed identically. New Javascript is the prototypical userscript that expects JavaScript code. New Remote lets you add a remote hosted userscript or style by entering the web address, with the example given as an https URL ending in .user.js. So remote styles are also treated as first class objects, which is a design choice worth noting if you expected a separate stylesheet surface. The surrounding controls are straightforward: the extension button opens the interface, the filter bar filters sidebar items by name, the sort button changes the order by name or modified time, and an item toggle enables or disables an individual item without deleting it.
The repository builds four Safari variants from one Svelte and CodeMirror front end
The repository is a Safari extension project with an xcode/ app project, and GitHub lists its primary language as Swift. The root carries a package.json marked private and of type module, with Vite as the dev server and Svelte 5 with the Svelte Vite plugin as the UI layer, CodeMirror 5 as the editor, marked for rendering, and separate eslint, prettier and stylelint configurations. The build scripts are the interesting part because there are four of them and they split on the same axis twice, once by platform and once by Safari version: build:mac-safari-15, build:ios-safari-15, build:mac-safari-16.4 and build:ios-safari-16.4, each setting a SAFARI_PLATFORM environment variable to mac or ios and calling a matching script under scripts/. The dev counterparts mirror them as dev:mac-safari and dev:ios-safari. The entry points are named by role at the root, including entry-ext-background.html, entry-ext-action-popup.html, entry-ext-extension-page.html and entry-app-webview.html, with an xcode/ directory for the app project and a fastlane/ directory for distribution.
The release line is a beta with a date stamped onto the tag
The versioning tells you where the project is. The three most recent tags are v5.0.0-beta.23+20261016 published 2026-10-16, v5.0.0-beta.23 published 2026-05-10, and v4.8.6 published 2026-01-10. Two things follow. The project is on a 5.0.0 beta line, so the major version that most users would consider stable is the 4.x series, whose latest release is v4.8.6. And the newest tag carries a date suffix after a plus sign, which is a build identifier rather than a semantic version, so sorting or comparing these tags by semver tooling will not behave the way you expect. The repository is not archived and the last push is dated 2026-10-16. Development progress is tracked on a GitHub project board linked from the README rather than in a changelog file, so there is no in-repository release history to read.
Editorial conclusion
Userscripts fits a Safari-only workflow where you want a script editor in the browser rather than a library of preinstalled scripts, and it does not fit anyone cross-browser, since the whole project is Safari specific. Four things to check before you rely on it. Distribution is the App Store only, since versions before 4.x were downloadable from the repository and that stopped when Apple changed how apps built with the WebExtension API could be distributed. The iOS app cannot detect whether the extension is enabled in Safari, so its interface only sets the scripts directory and tells you nothing about state. If you sync through iCloud, files can be evicted, and the documented workaround is to set keep downloaded on the folder since macOS 15 and iOS 18. And the current line is a 5.0.0 beta, with the newest tag carrying a date suffix. The last push is dated 2026-10-16.
Frequently asked questions
How do I install Userscripts on iOS or macOS?
Through Apple's App Store only, for both iOS and iPadOS and macOS. Versions before 4.x were downloadable from the repository, but that stopped because Apple changed how apps built with the WebExtension API can be distributed. You need iOS 15.1 or higher, or macOS 12 or higher with Safari 14.1 or higher.
How do I use Userscripts in Safari on an iPhone?
Open the app and set the userscripts directory, then enable the extension in Safari from Settings under Safari and Extensions, or from the AA button on iPhone, and grant permissions. You then install a script by visiting a .user.js URL where the extension ends the path rather than the query or hash, or by saving .user.js files into the directory you set. The iOS app has no built-in script editor.
Why does the Userscripts iOS app not show whether my extension is enabled?
The app cannot detect whether you have enabled the extension in Safari, so its prompt does not change after you enable the extension. The documentation states that the app interface is currently only used to set or change the userscripts directory, so the only reliable check is in Safari's own extension settings.
When will my Userscripts files be updated automatically?
Only when the script metadata contains both an @version tag and an @updateURL tag. The update button in the editor will not fetch a script that is missing either one. Note also that iCloud syncing between macOS and iOS can delay synchronisation and evict files, which is why the documentation recommends setting keep downloaded on the folder since macOS 15 and iOS 18.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/quoid-userscripts)Star history chart for your README
[](https://hysenlabs.com/projects/quoid-userscripts)Was this useful?