Separate Icons for macOS Tahoe vs. Earlier
Looks like Tahoe/Xcode beta 5 no longer lets me show my pre-Tahoe app icons in pre-Tahoe OSes. This is a bummer. I filed FB19437407 asking for the ability to do this.
I was also looking into how to do this. I had read that you could just keep your old icon in the .xcassets and use the same name for the new .icon file, and it would all just work: new icon on Tahoe and old icon on older versions of macOS. But I found that the old icon didn’t make it into the built app, and even the generated .icns file for backwards compatibility was low-resolution.
By default, yes,
actoolwill ignore .xcassets compatibility bitmaps that match the name of your app icon, and will instead substitute its own. However, if you use the super duper secret undocumented--enable-icon-stack-fallback-generation=disabledflag, it won’t. See here. This worked as of db4; I really hope they didn’t break it in db5.
This did not work for me with beta 5.
Václav Slavík found that it does work to separate names for the .iconset (for CFBundleIconFile) and .icon (for CFBundleIconName), not putting either in .xcassets, and this seemed to work for me, at least with his test project. But this approach didn’t work for Siracusa.
There’s apparently something special about app icons stored in Assets.car, it’s not just the name, and that’s what is throwing a wrench into things.
Previously:
Update (2025-08-09): John Siracusa:
The approach used in the [new version of the] sample project referenced here did work for me.
It uses a shell script to call actool and PlistBuddy.
Update (2025-08-11): John Siracusa:
Update: an app built this way is rejected by App Store Connect with the following error:
ITMS-90236: Missing required icon - The asset catalog in the application bundle does not contain an icon of size 512pt x 512pt @2X.
I changed the
actoolcommand line in the custom build phase to include the Assets.xcassets file path as the first argument (right before the existing .icon path argument) and then added the--include-all-app-iconsoption. That seemed to satisfy App Store Connect while still showing the pre-Tahoe icon on pre-Tahoe versions of macOS and the Tahoe icon on Tahoe.
Update (2025-08-12): Václav Slavík:
Passing the undocumented flag plus
--include-all-app-iconsand having same-named AppIcon in Assets.xcassets seems sufficient and is much simpler. I updated the example repo.
See also: James Thomson.
Update (2025-09-10): John Siracusa:
Hey, I got a response to one of my Feedbacks!
Me: “In Xcode 26 beta 4, if a Mac app included a new Tahoe-style .icon file with the same name as its existing app icon in its .appiconset file, the Tahoe-style .icon would show up in Tahoe and the pre-Tahoe icon from the .appiconset would show up in pre-Tahoe versions of macOS.
In Xcode beta 5, this no longer works. The Tahoe .icon is shown on all versions of macOS.”
(1 month passes)
Apple: “Please know that this is by design.”
Update (2025-11-12): John Siracusa:
Xcode 26.1 no longer supports this technique for building a Mac app that shows a Tahoe-style icon in macOS 26 and a non-Tahoe-style icon in earlier versions of macOS.
Previously:
Update (2026-02-04): John Siracusa:
I rubber-ducked with it for a while and came up with a new, terrible approach:
1. Copy the Assets.car file from a build of my app made with Xcode 26.0.1 into the repo.
2. Add a new build phase that replaces the built Assets.car with the saved “good” Assets.car file.
It works! But I need to use Xcode 26.0.1 or earlier if I ever want to change my icon.
9 Comments RSS · Twitter · Mastodon
It broke even for Apple. XC26 betas 2-4 had the original beta icon on macOS < 26. Now with beta 5, it's the disgusting Tahoe icon. Not just for Xcode, but for Simulator, Instruments, etc. Yuck
@someone that's the thing. That means basically abandoning the entire platform. You've got maybe a year until it starts getting harder and harder to not be on at least Tahoe.
As ATP and Siracusa recently pointed out, it's like this because there is no competition. In areas like games where there is little to no lock-in, the developers really care about the interface looking good and working well.
With operating systems, you get to pick Windows or macOS. Or have fun getting Linux to work for everything you need. Maybe it will maybe it won't but it will definitely be an adventure.
So Apple has very little incentive to make it excellent.
Am I missing something. The example project doesn't say what's been done, there's reference to a build phase script with a conflicting story of parameters, but I don't see such a build phase in the project file, these scripts I see allusions to mention an "AppIconGood" ¯\_(ツ)_/¯. Can someone please summarize on one post what one needs to do to achieve .icns on pre-Tahoe, .icon Tahoe and later. Thanks.
@Pierre Houston
If you're submitting to the mac app store, then I'm not sure what additional requirements there are for icons, and I recall seeing some discussion of that in those mastodon threads.
But I'm developing apps using Qt's toolchain for good ol' non app store distribution, which means I needed to find out how to get both a Tahoe and pre-Tahoe icon working without an Xcode project. Here's my approach:
1. I still include a .icns in the app bundle's resources directory
2. I use Icon Composer from the Xcode 26 beta to create a .icon file for the Tahoe icon.
3. I make sure both the .icns and .icon file have the same name, e.g. AppIcon.icns and AppIcon.icon
4. I use Xcode 26's actool to bundle the .icon file to an Assets.car file, with the following command:
actool AppIcon.icon --compile output --app-icon AppIcon --enable-on-demand-resources NO --development-region en --target-device mac --platform macosx --enable-icon-stack-fallback-generation=disabled --include-all-app-icons --minimum-deployment-target 10.14 --output-partial-info-plist /dev/null
Change the names as appropriate for your own files. Note too that I have a folder named output in the same directory from which I'm executing this command, hence '--compile output'.
5. I add the following keys to Info.plist:
CFBundleIconFile
AppIcon.icns
CFBundleIconName
AppIcon
That seems to do the trick. I think there may be some command line arguments in that call to actool that aren't necessary for my use case, because I'm not also including an old style icon in Assets.car, and I think (but am not 100% sure) that some of the trouble others were having was getting actool to generate an Assets.car with both old and new icons co-existing properly.
@Bri
Thanks. But I have, as normal, my icns within my Xcode project's asset catalog, so I think I'll wait to hear what others discover / reveal.
Also, it wasn't clear if you meant that you used actool *once* to add the icon to your asset catalog ahead of time, or do it at build time in a script build phase. Other suggesting linked to by this post mention a build phase. So the .icon can be added to an asset catalog, but only in actool and not in Xcode's UI? Weird. Anyway I'm currently not planning to do that.
Heh so I exported a PNG from icon composer and added them to asset catalog to avoid squircle jail. Using icon composer ensured I got the masking right.
Issue with this: Looks fine pre-Tahoe but macOS Tahoe the System automatically seems to apply a lighting effect to all icons (regardless of whether you built your app on the new Xcode or not). But when you export a png from icon composer, it includes the lighting effect in the png (and there doesn't seem to be a way to export a png without the lighting effect). So on Tahoe the icon png has a lighting effect but it gets a double lighting effect and it looks bad.
I remember back in the early iOS days they would apply a gloss lighting to every app icon but there was an Info.plist key you could use to turn it off...is there anything like that for macOS Tahoe?
So you can export from icon composer without the lighting effect.
1) Customize the Toolbar
2) add a FX toolbar item and toggle it off.
3) Then export.
Weird that the option to turn off FX is not in the export panel though.
Hey,
I am so confused as to why Apple would do this. As a non-developer developer, it now seems impossible to put a simple app in the Finder window toolbar. I guess I now have to turn my tiny AppleScript app into a Finder Service just to put it into a window toolbar and have it look even half-integrated.
What I am NOT confused about is how the Tahoe interface objectively sucks. They have heavily consumed the liquid glass corporate kool-aid even though it is completely broken. Basic tenets of UX design and accessibility engineering have been thrown out. Transparency is not an aid to legibility!
They can't even get their own toolbars right. Look at the System Settings window in dark mode for an example. There are so many wretched design choices and examples of flubbed execution--I could go on and on, but will not.
Anyway, sorry for venting here. Was just set off by the release today of the new Pages, etc. and really don't need to see my document content _under_ the (ghastly) toolbar buttons. How is this visual information, um, informative?
I'm also missing the Apple hacker ethos for customization in this OS. Steve Jobs is rolling (and cursing) in his grave.
Ean