Why macOS stops our apps on first launch, and how to open them

You download one of our apps, unzip it, move it to Applications and double-click. macOS refuses and tells you it can't verify the app. That message is the reason this article exists, so here is what is going on and what to do about it.

The short version is that our release builds are ad-hoc signed and not notarized by Apple. macOS treats an app like that with suspicion the first time it sees it. You confirm once, and after that the app opens like any other.

The longer version is worth a few minutes, because "can't be verified" sounds worse than it is. It still deserves a real answer before you click past it.

Three levels of signing

macOS knows several kinds of code signature, and they answer different questions.

Ad-hoc signed. The app carries a signature with no identity attached. It records hashes of the app's contents, so macOS can tell whether the bundle was changed after signing. It says nothing about who made it. On Apple Silicon Macs, code has to be signed at least this way to run at all. Our build scripts sign every app ad hoc.

Developer ID signed. The signature comes from a certificate Apple issues to members of its developer program. It ties the app to a named developer, and Apple can revoke the certificate if it is abused.

Notarized. The developer also uploads the signed app to Apple, which runs automated checks and issues a ticket. Gatekeeper accepts a notarized app on first launch with a short confirmation.

Our apps are at the first level. The signature protects the bundle against changes after the build. Apple has not vouched for it, and macOS says exactly that.

Why it asks once

When a browser downloads a file, macOS marks it with a quarantine attribute called com.apple.quarantine. The first time you open a quarantined app, Gatekeeper checks it. An app without Developer ID and notarization fails that check, so macOS blocks it.

Once you approve the app, macOS records the exception and stops asking for that copy. A new version is a new download with a new quarantine flag, so expect the same question after an update. ScreenShare adds one more wrinkle. Because its releases are ad-hoc signed, macOS may also ask for the screen and camera permissions again after you update it.

Opening the app, step by step

1. Download <App>-<version>-macos.zip from the app's page, unzip it and move the .app into /Applications.
2. Open the app once. macOS says it can't check the app. Click Done.
3. Open System Settings > Privacy & Security and scroll down to the security section. You'll see a line about the blocked app with an "Open Anyway" button.
4. Click "Open Anyway" and confirm. The app starts, and from then on it opens normally.

On recent macOS versions, the old trick of right-clicking the app and choosing Open no longer gets past the block for apps that aren't notarized. The Privacy & Security route is the one that works.

If you prefer Terminal, you can remove the quarantine flag yourself:

xattr -dr com.apple.quarantine /Applications/DirCompare.app

-d deletes the attribute and -r applies that to every file inside the bundle. Replace DirCompare with the app you installed. Without the flag, macOS no longer treats the app as a fresh download and doesn't run the first-launch check.

Both routes do the same thing in the end. You are telling macOS that you trust this particular copy. That's why the next step comes before either of them.

Check the download before you trust it

Every release ships two files, the app as <App>-<version>-macos.zip and a matching .sha256 file with its SHA-256 checksum. Put both in the same folder and run:

cd ~/Downloads
shasum -a 256 -c App-1.0.0-macos.zip.sha256

Use the file names you actually downloaded. If the zip matches, shasum prints the file name followed by OK. If it prints FAILED, delete the zip and download it again.

Be clear about what this proves. A checksum catches a broken or incomplete download, and it catches a zip that differs from the one we published. It can't protect you if someone controls the release page and swaps both files at once, because then the checksum matches the wrong zip. For that case the stronger check is to skip our binary entirely.

Build it yourself

Every app is open source under the MIT licence, and each repository on GitHub goes public with the app's first release. Each repository has a build script, and its README lists what you need, which is a recent macOS plus Xcode or the Command Line Tools. For DirCompare it looks like this:

git clone https://github.com/Tealow2610/dir-equal.git
cd dir-equal
./scripts/build-app.sh --install

That builds the app, signs it ad hoc on your own Mac and copies it to /Applications. An app you build locally never passes through a browser, so it has no quarantine flag and macOS opens it without the first-launch block.

You also get to read what you're running. The vault code in 2Password, the sync executor in DirCompare and the tax tables in Reisekosten are all there to inspect. For apps that handle your passwords, your files or your expense reports, I think that matters more than a ticket from Apple. A notarization ticket tells you Apple's automated checks found nothing. The source tells you what the program does.

Shipping without notarization moves one small step of work from us to you, at first launch. Publishing checksums and source is how we try to make that step something you can verify instead of something you have to take on faith.

Pick an app, download the zip and its .sha256, run the checksum and open it through Privacy & Security. Or clone the repository and build it yourself. The open source page has these steps in short form, plus the build requirements. Each app page lists its own build command, and the changelog shows what changed in each release.