How to add a custom icon to an app without breaking its signature

I’ve recently been extolling the virtues of apps checking their own integrity, and we’re all aware that Mojave and Catalina introduce tougher checks on app signatures. One of the casualties of this is the dubious practice of some users who customise apps in various ways: altering the contents of app bundles can cause them to fail signature checks, and stop them running.

This article explains how you can safely change the icon displayed by an app without breaking its signature, even when it has yet to go through full ‘first run’ checks with its quarantine flag set.

What you can’t do is tamper with the app’s icons inside its Resources folder. Although the Resources folder is excluded from some signature checks, it is checked at first run and now on some other occasions. Change anything in there and the app is at significant risk of failing more extended signature checks, and may as a result stop launching.


The ‘official’ way to change an app’s icon uses the Finder’s Get Info dialog. Click on the icon in the top left corner to select it, and you can paste in another icon in its place.


If you want to use an altered version of the existing app icon, perhaps with a version number superimposed, copy the original icon into a suitable editor such as GraphicConverter using PNG format, change it to your liking, then ensure that it uses a single layer. If you’ve added superimposed text, for example, you may need to save it as a PNG and reopen that file, or the text may be omitted.


Select the whole of the modified icon, with its transparent background, copy and paste it into the Get Info dialog for the app.

What happens then is rather ingenious. Instead of the Finder altering the icons within the app bundle, a new file named Icon? is created at the top level in the bundle, alongside the Contents folder. That file contains the custom icon, but not as data, which could break the signature, but as a traditional resource fork, an extended attribute of type, as shown in xattred.


When checksums/hashes are calculated for a bundle’s signatures, they only take into account the data fork of each file in the bundle, not their extended attibutes. This is essential because of the quarantine flag, which is also attached to files as an extended attribute. If signature checksums included extended attributes, attaching quarantine flags would instantly break the signature, so macOS wisely excludes them.

That copy of your app now has the custom icon attached inside it without breaking any signature checks. The only disadvantage with this method is that, if the app is passed through a medium which doesn’t copy all extended attributes, the custom icon could be stripped.

(Thanks to Joxster for inspiring this.)