Userscripts for Safari: an open-source manager for iOS and macOS
An open-source userscript manager for Safari
At a glance
- What is it?
- Userscripts is a Safari app extension that loads .user.js and CSS files from a folder you control. It is a good fit if you already write or collect scripts; it is not a Tampermonkey replacement with a built-in script catalogue.
- Who is it for?
- Adopt Userscripts if you use Safari on macOS 12 or iOS 15.1 and you are comfortable managing .user.js files in a folder, especially if you want an editor on the Mac and iCloud sync between devices. Do not adopt it if you need a script catalogue, Android or Firefox support, or a stable release channel: the newest published build is v5.0.0-beta.23+20260727 from 2026-07-27.
- 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 64 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 September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What problem Userscripts solves, and who it is for
Safari has no built-in way to run a .user.js file. Userscripts fills that gap with a Safari app extension plus a companion app that stores scripts as ordinary files in a directory you choose. The README describes it as "an open-source userscript editor for Safari", and the repository topics list safari, safari-app-extension, userscript and userscript-editor. The audience is narrow and specific: people on macOS or iOS who want to modify pages with their own JavaScript or CSS and who are willing to keep those files somewhere they can see.
The design assumes you already have scripts. There is no catalogue, no store, no recommended-scripts feed in the documented interface. You add a script by writing one in the editor, by pointing the app at a remote URL, or by dropping a file into the scripts directory. If you expect to browse and one-click install from a gallery, this is the wrong shape of tool.
The app is not a general browser-automation framework either. It runs userscripts and userscripts that are pure CSS, which the README calls a "New CSS" item. That is the whole scope.
How the extension, the app and the scripts directory fit together
Three pieces are visible in the repository layout. The Xcode project lives under xcode/, the web extension entry points are top-level HTML files (entry-ext-background.html, entry-ext-action-popup.html, entry-ext-extension-page.html, entry-app-webview.html), and the interface is built with Svelte and Vite. The package.json shows the toolchain: svelte, vite, codemirror for the editor, marked for rendering, and eslint, prettier and stylelint for linting. So the app UI is a web view, and the extension is a standard Safari web extension bundle.
The data flow is file-based rather than database-based. Scripts live in a directory that the app reads and the extension injects. On macOS the README says you do not need to select a directory unless you plan to sync between devices, because a default is used automatically at ~/User/Library/Containers/Userscripts/Data/Documents/scripts. Choosing a custom location is what makes the files reachable from an external editor such as Sublime Text or VSCode.
Metadata drives the features. The README states the Update button only works for scripts whose metadata contains both @version and @updateURL. A remote item added through "New Remote" takes a web address, with the README's example being https://www.k21p.com/example.user.js. Everything else in the interface is local: toggles, filtering by name, sorting by name or modified time, and the editor's Discard and Save buttons with Command + S as the save shortcut.
Installing Userscripts on macOS and iOS, and running a first script
Installation goes through Apple's App Store for both platforms. The README is explicit that direct download is gone: versions prior to 4.x were distributed from the repository, but changes in how Apple allows WebExtension apps to be distributed ended that. Requirements are macOS 12 or higher with Safari 14.1 or higher, and iOS 15.1 or higher.
On iOS, the README lists two steps after installing the app. Set a directory for saving and loading userscripts (since v1.5.0 a local default is set automatically), then enable the extension in Safari and grant permissions, either from Settings > Safari > Extensions or from the AA button in Safari. The README recommends choosing "Always Allow" for all websites for the best experience.
On macOS the directory step is optional. If you skip it, the default location is used.
~/User/Library/Containers/Userscripts/Data/Documents/scriptsThat path is where the app stores scripts by default according to the README. Point an external editor at it if you prefer writing scripts outside the app.
Installing a script on iOS has two documented routes. Visit a .user.js URL in Safari and open the extension popup to get an installation prompt, or save a file with the .user.js extension directly into the scripts directory. The README adds a constraint worth reading twice: the URL must end with .user.js in the path portion, not in the query or hash portion. A URL shaped like https://www.k21p.com/example.user.js is what the popup expects; the README notes that ?QUERY or #HASH suffixes on the .user.js segment will not be treated the same way.
The macOS editor is the part iOS lacks. The README says the iOS version does not include the script editor, so on iPhone or iPad you edit files in the directory with a third-party code editor that supports in-place editing. If your workflow depends on the built-in editor, that workflow is macOS-only.
iCloud sync, file eviction and the limits of the iOS app
Selecting an iCloud folder is the documented way to share scripts between macOS and iOS. The README attaches two warnings to it. Synchronization may be delayed, and files may be evicted by iCloud optimization, with a link to issue #424. Since macOS 15 and iOS 18 the README advises setting "keep downloaded" on the folder to avoid eviction. This is a real failure mode, not a footnote: a script that has been evicted is not available to the extension until it is downloaded again.
A second limitation is stated plainly in the README. The iOS app cannot detect whether you have enabled the extension in Safari, so the app prompt does not change after you enable it. The iOS app interface is only used to set or change the userscripts directory. Anyone expecting the app to confirm that everything is wired up will be misled by a screen that looks unfinished but is behaving as designed.
A third constraint is the platform boundary itself. The repository topics mention safari and safari-extension, and installation is App Store only. There is no Chrome, Firefox or Android build, and no sideloading path on macOS anymore. If your team is not on Safari, the project cannot help you.
Finally, the release channel matters. The recent releases are v5.0.0-beta.23+20260727 (2026-07-27), v5.0.0-beta.23 (2026-05-10) and v5.0.0-beta.22+20260406 (2026-04-06). The 5.x line is published as betas, and the README still documents 4.x-era behaviour such as the removed direct download. The last push to the repository was on 2026-07-27, so the project is not abandoned, but anyone who needs a stable numbered release should look at what the App Store is currently serving rather than assuming the repository tag is what they will get.
Userscripts compared with Tampermonkey and Safari's own extension options
Tampermonkey is the obvious alternative and the difference is architectural, not cosmetic. Tampermonkey ships a large script catalogue and a dashboard inside the extension, so a new user can install a script without ever touching a file system. Userscripts inverts that: the file system is the source of truth, and the app is a viewer and editor over a directory. The practical consequence is that you can version, back up and edit your scripts with tools you already use, but you also have to find and manage the scripts yourself.
Safari's own extension support is the other comparison point, and the README explains why it is not equivalent. Apple's distribution rules for WebExtension-based apps forced the project to stop offering direct downloads before 4.x. That same rule set is why Userscripts is App Store only, and it is the reason a self-hosted or enterprise-deployed build is not a documented option.
There is also a lighter alternative for one narrow case. If all you need is CSS injection, the README's "New CSS" item type covers it without any JavaScript. But if you need @require, @grant or a userscript API surface beyond what this project documents, the README's API section is the place to check before assuming parity with other managers.
Licence, maintenance and what upgrading costs you
The project is licensed GPL-3.0. That matters if you plan to fork the app or ship a modified build, because derivative distribution carries the same licence obligations. It does not affect writing your own userscripts, which are your files in your directory. This is a description of the licence identifier in the repository, not legal advice; read the LICENSE file for the actual terms.
On maintenance, the last push to the repository was on 2026-07-27, and the most recent release is the beta v5.0.0-beta.23+20260727 from the same date. The repository is not archived. That is the factual position; the README does not document a release cadence or a support window.
Upgrade cost is mostly about the beta channel. The 5.x releases are betas, and the README documents behaviour that spans versions, including the note that direct download ended before 4.x and that the automatic default directory arrived in iOS v1.5.0. If you pin to whatever the App Store serves, you are accepting that the version under you can change without a repository tag you chose. The README does not document rollback, so there is no stated way to return to an earlier build once the App Store updates.
What you control is the script layer. Because scripts are plain files, you can keep them in git and review diffs independently of app updates. That is the mitigation the architecture offers, and it is the reason the file-based design is worth the extra setup.
Editorial conclusion
Adopt Userscripts if you use Safari on macOS 12 or iOS 15.1 and you are comfortable managing .user.js files in a folder, especially if you want an editor on the Mac and iCloud sync between devices. Do not adopt it if you need a script catalogue, Android or Firefox support, or a stable release channel: the newest published build is v5.0.0-beta.23+20260727 from 2026-07-27. Before relying on it, confirm your OS and Safari versions, decide whether the default scripts directory or a custom one fits your editor, and check that any script you depend on carries @version and @updateURL if you want the in-app update button to work.
Frequently asked questions
How do I use userscripts in Safari with the Userscripts app?
Install the app from Apple's App Store, then enable the extension in Safari and grant permissions. On iOS you also set a directory for saving and loading scripts; on macOS a default directory is used unless you choose another one. After that, visiting a .user.js URL and opening the extension popup gives you an installation prompt.
How do I install a userscript on iPhone or iPad?
The README gives two routes: visit a .user.js URL in Safari and open the extension popup to see an installation prompt, or save a file with the .user.js extension directly into the scripts directory you set. The URL must end with .user.js in the path portion, not in the query or hash portion.
Does the Userscripts iOS app have a script editor?
No. The README states the iOS version does not include the script editor that the macOS version provides. On iOS you can edit script files in the directory you set using a third-party code editor that supports in-place opening and editing.
How do I use userscripts on a Mac?
Install Userscripts from Apple's App Store on macOS 12 or higher with Safari 14.1 or higher, then enable the extension. You do not need to select a scripts directory unless you want to sync between devices, because a default directory is set automatically. The macOS version includes the script editor that iOS lacks.
How do I use userscripts in the Userscripts app on iOS?
Open the app to set the directory used for saving and loading userscripts, then enable the extension in Safari under Settings > Safari > Extensions and grant permissions. The README recommends choosing "Always Allow" for all websites. The iOS app cannot detect whether the extension has been enabled, so its prompt does not change afterwards.
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)