Safari

Install on Safari

Safari does not load an extension folder. Apple requires every Safari extension to be a signed Mac app, so the package has to be converted into an Xcode project and run from there.

This is the most involved of the three, and it needs Xcode. If you would rather not, the same account works in Chrome or Firefox alongside Safari.

Download the source package

The Chromium build is the input — Apple’s converter reads the standard Manifest V3 format.

You need full Xcode from the Mac App Store, not just the Command Line Tools. The converter ships inside Xcode, and xcrun cannot find it otherwise.

  1. 1

    Unzip the package.

    Note where the folder ends up; the next command takes its path.
  2. 2

    Run Apple’s converter on it.

    In Terminal:

    xcrun safari-web-extension-converter /path/to/unzipped-folder

    It asks a few questions — the defaults are fine — then opens an Xcode project it generated.

  3. 3

    Build and run it from Xcode.

    Press the play button. A small Mac app opens with a button that takes you to Safari’s extension settings.
  4. 4

    Allow unsigned extensions in Safari.

    Safari → Settings → Advanced → tick Show features for web developers. Then in the Develop menu, choose Allow Unsigned Extensions.

  5. 5

    Enable Locus, then click the icon and choose Connect to Locus.

    Safari → Settings → Extensions → tick Locus. Grant it access to the sites you read on when asked.

Allow Unsigned Extensions resets every time Safari restarts. You will re-tick it each session until the extension is distributed as a signed app, which needs an Apple Developer account. That is a limit Apple imposes on unsigned extensions, not something the package can work around.

When it does not work

xcrun: unable to find utility "safari-web-extension-converter"

Only the Command Line Tools are installed. Install Xcode from the Mac App Store, open it once to let it finish setting up, then point the tools at it: sudo xcode-select -s /Applications/Xcode.app and try again.

Locus does not appear under Safari’s Extensions.

The app has to have been run at least once from Xcode, and Allow Unsigned Extensions has to be ticked in the Develop menu in the current Safari session. Both reset independently, which makes this look intermittent.

It says the publisher refused the download.

That is an access answer, not a bug. If the page shows Get access or Purchase PDF, or the URL carries redirectedFrom=fulltext, you are looking at an abstract. The extension uses your session and nothing more, so if you cannot open the PDF yourself it cannot either.

No paper found on this page.

The page does not publish citation_* metadata, which is what nearly every publisher emits for Google Scholar. Send us the URL and we will add a fallback for that site.

Nothing changed after I updated the extension.

The popup is re-read from disk every time it opens, but the background script is not — it is only re-registered when you reload the extension from your browser’s extensions page. A fix to the download can look like it did nothing while the new popup sits in front of you. The version number on the extension’s card is the visible sign the reload took.