Add custom file and folder icons in Sequoia

Adding your own custom icons to files and folders goes back a long way, to Classic Mac OS where it was widespread. With all the changes brought in recent versions of macOS, particularly Sequoia’s changes to Quick Look, this article explains how you can still replace standard icons with your own.

Add a custom icon

You can copy an icon already used by an app, file or folder on your Mac by selecting it and using the Finder’s Get Info command. In that dialog, select the small icon at the top left of the window, and copy it.

If you want to modify or design your own icons, a good graphics editor like GraphicConverter is fine. Work with a PNG image with a transparent background and dimensions of 1024 x 1024 pixels. When it’s ready, select all and copy it.

To add your custom icon to an app, file or folder, select it in the Finder, open the Get Info dialog, select its current icon at the top left, and paste in your replacement.

Where it doesn’t work

There are some items that you can’t add a custom icon to. Any app, file or folder in the Signed System Volume can’t be modified in any way, and those in folders where you don’t have write access won’t work either. If you really wanted to display one of those with a custom icon, the only way to do that is to create an alias, and paste your replacement icon into Get Info for that alias.

How it works

When you add a custom icon to a file, the icon is converted into a traditional resource of icns type, and written to an extended attribute of type com.apple.ResourceFork attached to that file. That xattr is the modern equivalent of the old resource fork used in Classic Mac OS. It’s also surprisingly large, typically around 330 KB, which can bring its own problems as described later.

When you add a custom icon to a folder, including one that’s enclosing a bundle like an app or RTFD document, it isn’t added as an extended attribute to the folder, but is added to a hidden file named Icon? (the last character isn’t really a ? but is actually Carriage Return, UTF-8 0D) inside that folder. Normally, icons to be displayed for an app are saved as an AppIcon.icns file inside the Resources folder within the app bundle, but modifying that could break the app’s signature. A custom icon dodges that by being saved outside the bundle itself, and in an extended attribute rather than as data.

Aliases are complicated

Add a custom icon to a folder, then make a Finder alias to it. What you’ll then see is a muddle.

In the Get Info dialog, the Preview shows the custom icon, but the icon displayed in the Finder is the default folder with an alias arrow superimposed. To get the alias to display your custom icon, you have to Get Info on the alias and paste that icon into the top left.

This rule, that the Preview shows the icon associated with the original, while the regular icon shown is that for the alias itself, extends to bundled apps. As you can’t add a custom icon to a bundled app, because its bundle can’t be changed in any way, one workaround might be to create an alias to the app and add your custom icon to that alias.

What then happens is that your alias displays its custom icon, but the Preview shown is the original app icon that you can’t change.

The biggest problem with attaching custom icons to aliases comes when the alias needs to be remade, for example by my app Alisma. The remade alias is then likely to lose its custom icon, which you’ll have to paste in again.

iCloud folders are complicated too

Just when you think you’ve understood how custom icons work, you try using them in iCloud Drive, and discover that there are some further subtleties.

iCloud Drive doesn’t like storing Icon? files in the cloud, and even if it would do so, it couldn’t upload the crucial com.apple.ResourceFork extended attribute, as iCloud doesn’t like them. Furthermore, the standard custom folder icons that you see in iCloud Drive aren’t created by the same mechanism, and can’t be overruled by your own icons.

The end result is that, while you can add custom icons to plain folders in iCloud Drive, the only client that will see them is the Mac that customised them in the first place, as that’s the one with the Icon? file and its extended attribute. Other Macs and devices won’t see the custom icon, unless of course you add it to the same folder on them. The same goes for custom icons on files.

In the recent past, custom icons have been unreliable in iCloud Drive. That was because, when the folder was evicted from local storage, the hidden Icon? file was sometimes lost, and couldn’t be replaced when the contents of the folder were downloaded again. That appears to have been fixed recently, and they should now be more stable in macOS Sequoia.

Happy customising!