xattr -cr: what it does and when to use it

xattr -cr strips the extended attributes from a file or app on macOS, including the quarantine flag that makes Gatekeeper block downloaded apps. Here's what the command really does, a safer version of it, and how developers can ship apps that never need it.

Scissors cutting the string of a tag tied to a parcel

xattr -cr is a macOS Terminal command that removes every extended attribute from a file, or from a folder and everything inside it. People run it on a downloaded app to remove the quarantine flag, which is what makes macOS show messages like "is damaged and can't be opened".

xattr -cr /Applications/SomeApp.app

It works, and it's blunter than most people realise. This page covers what it does, the more precise command you probably want, when it's reasonable to use, and, if you're the developer of the app, how to make sure your users never have to type it.

What xattr -cr does, piece by piece

  • xattr is the built-in macOS tool to "display and manipulate extended attributes". Extended attributes are extra bits of metadata stored alongside a file, separate from its contents.
  • -c means clear: remove all attributes, whatever they are.
  • -r means recursive: if the path is a folder, do the same to everything inside it. A .app is a folder, so this covers every file in the app.

So xattr -cr SomeApp.app deletes all extended attributes from the app bundle and every file in it. It doesn't change the app's code and it doesn't need sudo for files you own.

The quarantine attribute

The attribute people are really after is com.apple.quarantine. When you download a file with a browser, a mail client or a chat app, that app tags the file with it. The tag records that the file came from the internet, roughly when, and which app downloaded it.

You can see it:

xattr -l SomeApp.app
com.apple.quarantine: 0083;673a1b2c;Safari;F643CD5F-6071-46AB-83AB-390BA944DEC5

When you open a quarantined app for the first time, Gatekeeper checks it. If the app is signed with an Apple Developer ID and notarized by Apple, you get the normal "downloaded from the internet, are you sure?" prompt and it opens. If it isn't, macOS refuses, with a message that depends on the macOS version and on what's wrong:

  • "SomeApp is damaged and can't be opened. You should move it to the Trash."
  • "Apple could not verify SomeApp is free of malware that may harm your Mac or compromise your privacy."
  • "SomeApp can't be opened because it is from an unidentified developer."

The "damaged" wording is misleading. Usually nothing is corrupted; the app is unsigned, or its signature broke, and it has the quarantine flag. Remove the flag and Gatekeeper never runs that check.

A safer command: remove only the quarantine flag

-c removes everything, and extended attributes aren't only quarantine. Finder tags, "where from" download info and some app-specific metadata live there too. If quarantine is what you want gone, delete just that one:

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

-d deletes the named attribute and leaves the rest alone. For a single file that isn't a folder, drop the r.

To check that it's gone:

xattr /Applications/SomeApp.app

On recent versions of macOS you may still see com.apple.provenance in the list afterwards. That's a different attribute that the system manages itself, and it doesn't cause the "damaged" message.

Is it safe to run xattr -cr?

The command itself is harmless. It deletes metadata, and the worst that happens if you run it on the wrong folder is losing some Finder tags and similar metadata.

What it does to your security is the real question. Quarantine is the trigger for Gatekeeper's malware and signature check. Removing it means "open this app without checking it". That's fine when you have a good reason to trust the app:

  • You built it yourself, or a colleague did
  • It's open-source software from the project's own releases page, and the project says it isn't notarized
  • It's an internal tool from your own company

It's a bad idea when a website you don't know tells you to paste the command to make a download work. Malware distributors have learned to include these instructions too. If you wouldn't run an unknown .exe on Windows, don't strip quarantine from an unknown .app.

Other ways to open a blocked app

You don't always need Terminal:

  • System Settings. Try to open the app once, then go to System Settings, Privacy & Security, and scroll down to the Security section. There's an "Open Anyway" button for the app you just tried. This is the route Apple intends, and on recent macOS versions it has replaced the old Control-click, Open shortcut.
  • Download it again. If the app is supposed to be signed and you still get "damaged", the download may be incomplete, or the app was modified after signing. A fresh copy from the developer's site is the first thing to try.
  • Ask the developer. If their app is triggering this for everyone, they need to know, because it's fixable on their side.

For developers: why your users see this, and the fix

If people are emailing you about "damaged" messages, or your README tells users to run xattr -cr, the cause is on the build side. Every one of these is fixable.

The app isn't signed with a Developer ID. Apps distributed outside the Mac App Store need to be signed with a Developer ID Application certificate, which requires the Apple Developer Program.

The app isn't notarized. Since macOS 10.15, Gatekeeper expects downloaded software to be notarized: you upload the build to Apple, an automated scan checks it, and you get a ticket back. Signing alone isn't enough.

xcrun notarytool submit MyApp.dmg --keychain-profile "notary" --wait
xcrun stapler staple MyApp.dmg

The ticket isn't stapled. stapler staple attaches the notarization ticket to the app or disk image, so Gatekeeper can verify it even when the Mac is offline.

The signature broke after signing. This is the classic cause of "damaged" on an app that was signed properly. Anything that changes the bundle after signing invalidates it: adding or editing a file, a build step that runs after codesign, or packaging with a zip tool that drops symlinks and resource data. Zip with ditto -c -k --keepParent MyApp.app MyApp.zip, or ship a DMG.

Nested code isn't signed. Frameworks, helper apps and command-line tools inside the bundle all need signatures, with the hardened runtime enabled, or notarization fails.

Check your build the way a user's Mac will:

codesign --verify --deep --strict --verbose=2 MyApp.app
spctl --assess --type execute --verbose MyApp.app

spctl should answer accepted and source=Notarized Developer ID. And test the real thing: download your release from your own website in a browser, on a Mac that has never seen the app, and open it. A build you run on the machine that made it never gets the quarantine flag, so it hides the problem.

To work out which of these is behind your users' reports, follow the developer guide to the "app is damaged" message. There's also a step-by-step guide to notarized macOS releases in CI.

The rest of shipping a Mac app

Once your app opens cleanly, the remaining pieces are how customers pay, how the app knows they paid, and how they get updates. The guide to licensing macOS apps walks through all of it, from adding a license key check in Swift to Sparkle updates. LicenseSeat handles the licensing and update side for apps sold outside the App Store, and takes 0% of your revenue.

Common questions about xattr -cr

What does xattr -cr do?

It removes all extended attributes from a file or folder, recursively. On a downloaded app, that includes the com.apple.quarantine flag, so macOS stops running the Gatekeeper check that was blocking it.

Is xattr -cr dangerous?

The command can't damage files. The risk is in what you use it for: it lets an app run without macOS checking its signature or scanning it. Only use it on software you have a good reason to trust.

Do I need sudo for xattr -cr?

Not for files you own, such as an app you copied into Applications yourself. If you get "Permission denied", the app belongs to another user or to root, and sudo xattr -cr will work.

What is the difference between xattr -c and xattr -d?

-c clears every extended attribute. -d deletes one attribute by name, as in xattr -d com.apple.quarantine file. The second is more precise and is usually what you want.

Why does macOS say an app is damaged when it isn't?

Because the app has the quarantine flag and fails the Gatekeeper check, typically since it's unsigned, not notarized, or its signature was invalidated after signing. macOS shows "damaged" for several of these cases, even when the file is intact.

Does xattr -cr work on Apple silicon Macs?

It removes the quarantine flag the same way. But Apple silicon Macs won't run native code with no signature at all, so a completely unsigned app can still fail to launch. Developers fix that by at least ad-hoc signing the build with codesign --force --deep --sign - MyApp.app.

How do I stop my own app from needing xattr -cr?

Sign it with a Developer ID certificate, notarize it with notarytool, staple the ticket, and package it without altering the bundle afterwards. Then test by downloading the release in a browser on a clean Mac.