What sizes does an ICNS file need?
Apple asks for each icon size in pairs, standard and Retina (@2x): 16, 32, 128, 256 and 512 points, so the largest image is 1024 × 1024 pixels (512 at @2x). App Store uploads have failed with an error asking for an .icns containing both the 512 and the 512@2x image. Each image goes into a slot named by a four-letter code. This page fills these:
| Slot | Size | Stored as | .iconset file |
|---|---|---|---|
is32 | 16 pt = 16 px | Compressed colour + alpha mask (s8mk) | icon_16x16.png |
il32 | 32 pt = 32 px | Compressed colour + alpha mask (l8mk) | icon_32x32.png |
ic11 | 16 pt @2x = 32 px | PNG | icon_16x16@2x.png |
ic12 | 32 pt @2x = 64 px | PNG | icon_32x32@2x.png |
ic07 | 128 pt = 128 px | PNG | icon_128x128.png |
ic13 | 128 pt @2x = 256 px | PNG | icon_128x128@2x.png |
ic08 | 256 pt = 256 px | PNG | icon_256x256.png |
ic14 | 256 pt @2x = 512 px | PNG | icon_256x256@2x.png |
ic09 | 512 pt = 512 px | PNG | icon_512x512.png |
ic10 | 512 pt @2x = 1024 px | PNG | icon_512x512@2x.png |
Why do some 16 and 32 px Mac icons look like noise?
The ICNS format has PNG slots for the 16 and 32 px sizes too (icp4 and icp5), and some tools have filled them, electron-builder among them until August 2026. But recent macOS versions draw PNG data in those slots as random noise when the icon sits inside an app: in Finder's list view and in a disk image's title bar. The maintainers of electron-builder, a Mac app packager, fixed exactly that in August 2026, and an independent test that booted macOS versions from 9.2 to 26 found the same on recent versions: those slots work in a loose .icns file but fail inside an app. The older compressed format with a separate alpha mask (is32 with s8mk, il32 with l8mk) rendered inside apps on every version it tested from 10.0 to 26, and in loose .icns files on all but 10.4, 10.14 and 10.15. So this page stores 16 and 32 px only in that older format, and uses PNG from 32 px Retina up, the same slots Tauri's icon tool writes. It also adds one byte that test found fixes macOS 12 to 26 dropping the last value of that compressed data inside apps.
We read every file back: Pillow (the Python imaging library) decoded all ten images of an .icns made on this page in Chrome, and each matched the image it was made from exactly. We have not opened these files on a Mac ourselves; the slot choices follow the tests above.
How do I change an icon on a Mac?
- Select the file, folder or app in the Finder and choose File › Get Info.
- Drag the .icns file onto the small icon at the top of the Get Info window. This keeps every size in the file.
Apple's own steps instead open an image in Preview, choose Edit › Copy, click the small icon in Get Info and choose Edit › Paste; to go back, select the small icon and choose Edit › Cut. That works with any image, so for a folder icon a PNG is enough, but copying from Preview pastes a single large image rather than the .icns with its small sizes. Copy the picture itself: pasting a copied file gives the generic document icon. If the Dock or Finder keeps showing the old icon, quitting the app, running killall Dock (or killall Finder) in Terminal, or restarting can refresh it; be wary of advice to delete system cache folders with sudo rm, which one user reported left a Mac unable to start.
Using the .icns in an app build
- Mac app bundle: put the file in Contents/Resources and name it in Info.plist with
CFBundleIconFile. - Electron (electron-builder): accepts a 1024 px PNG or an SVG and converts it itself, but a pre-built icon.icns skips that step, and the disk image's volume icon still uses .icns.
- Tauri: lists
icon.icnsas the macOS icon. - PyInstaller:
--icon app.icnsapplies it to the .app bundle. Given another format, it converts through Pillow, whose ICNS writer leaves out the 16 and 32 px standard sizes; this file has them. - Qt:
ICON = myapp.icnsin qmake, orMACOSX_BUNDLE_ICON_FILEin CMake.
The .iconset folder and iconutil
The second download is the same images as an .iconset folder, for Apple's own tool: run iconutil -c icns name.iconset on a Mac to build the .icns yourself, or add the PNGs to an Xcode asset catalog. iconutil is strict: forum answers trace its “Invalid Iconset” and “Failed to generate ICNS” errors to three things this download gets right: the folder must end in .iconset; the files must have Apple's exact names, icon_16x16.png, icon_16x16@2x.png, icon_32x32.png, icon_32x32@2x.png, icon_128x128.png, icon_128x128@2x.png, icon_256x256.png, icon_256x256@2x.png, icon_512x512.png and icon_512x512@2x.png; and each image must be square at the size its name says. One forum user also fixed the error by saving PNGs with an alpha channel, which these have in our Chrome test.
Shape and macOS 26 Tahoe
Apple's guidelines changed. Its 2024 guidance told Mac developers to draw the rounded-rectangle shape themselves; the current version says macOS icons are square and the system applies the rounded corners, from either a plain bitmap or an Icon Composer file. On macOS 26 Tahoe, app icons that do not fit the template are reported to be shown shrunk inside a grey rounded square. This page offers three shapes: as it is; with a margin (100 px of 1,024 on each side); or on a rounded square of your colour, 824 px with 185.4 px corners. Those figures are the ones developers give for Apple's Big Sur-era template on Apple's forums, not numbers from an Apple document.
ICO to ICNS
An .ico opens too. With the “As it is” shape, where the icon holds a size the .icns needs, that image is used as it is, and other sizes are drawn from the largest image in it; with a margin or rounded square, every size is drawn from the largest image. ICO images stop at 256 px, so the 512 and 1024 px Mac sizes are enlarged and look softer; the page warns when that happens. For the sharpest result, start from an SVG or a 1024 px PNG. To make Windows icons as well, use PNG to ICO or SVG to ICO.