PNG to ICNS on Mac: iconutil Drops a 1000px PNG, Exit 0

I put a 1000×1000 PNG into an iconset on this Mac mini, named it [email protected], and ran iconutil -c icns. It printed nothing and exited 0. The .icns it wrote had nine images instead of ten: the 1024-pixel one was gone, and sips now reported the icon's largest size as 512. A JPEG renamed to .png and a 1024×768 PNG got the same treatment: dropped without a word, exit 0. If you are converting a PNG to ICNS on a Mac, that is the failure to watch for, because nothing tells you it happened.

This post covers the built-in way to go from one PNG to a full .icns on macOS 26.4.1: the iconset folder, the ten file names, and the two tools involved, sips and iconutil. I tested 80 name-and-size combinations to find out what iconutil actually checks. I also opened all 65 apps in /System/Applications to see what Apple ships now that Tahoe icons come from Icon Composer. Every result below comes from runs on this machine today.

The short answer: PNG to ICNS in one block

Start from a square PNG of at least 1024×1024 pixels. The folder name must end in .iconset, and the file names must match Apple's pattern exactly.

SRC=icon-1024.png
mkdir MyIcon.iconset
for s in 16 32 128 256 512; do
  sips -z $s $s "$SRC" --out MyIcon.iconset/icon_${s}x${s}.png >/dev/null
  d=$((s*2))
  sips -z $d $d "$SRC" --out MyIcon.iconset/icon_${s}x${s}@2x.png >/dev/null
done
iconutil -c icns MyIcon.iconset        # writes MyIcon.icns next to the folder

# check: a full icon expands back to 10 files
iconutil -c iconset MyIcon.icns -o check.iconset && ls check.iconset | wc -l

The whole block ran in 0.19 seconds here. The final check is my addition, and it is the only part that catches the silent drop. A full .icns expanded back into 10 files. The one built with the 1000-pixel file expanded into 9, and an iconset containing only the 1024 file expanded into 1. All three conversions exited 0.

The ten names come from Apple's High Resolution Guidelines for OS X. The page is archived, but it is still the only place Apple spells out the pattern: icon_<points>x<points>[@2x].png, sizes 16, 32, 128, 256 and 512, with "no longer a 1024x1024 size. That's replaced by 512x512@2x."

What iconutil actually checks

I expected iconutil to read the size from the file name. It doesn't. I made iconsets that each held one file. I used all ten names and gave each one eight different pixel sizes, for 80 runs. The number in the name made no difference. Only two things mattered: whether the name ended in @2x, and the pixel size of the file.

So a 256-pixel file named icon_16x16.png is accepted and stored as the 256 image (chunk ic08). A 1024-pixel file named [email protected] becomes the 1024 image (ic10). Mislabelled files don't cause an error. They land in another size's slot. When two files map to the same slot, one replaces the other with no message. I tried this twice, and both times the file whose name sorted later won. In one run, an upscaled 16-pixel image saved as icon_16x16.png at 128 pixels replaced the real icon_128x128.png.

Whether you see an error depends on what else is in the folder. A bad file on its own gives Failed to generate ICNS. and exit 1, because nothing is left to write. The same bad file in an otherwise complete set is skipped, and the run exits 0. The full list of cases I tried:

What I did	Exit	Message	Result
Correct 10-file iconset	0	none	11 chunks, 834,211 bytes
1000×1000 PNG as [email protected]	0	none	1024 image missing
JPEG renamed to .png in the 1024 slot	0	none	1024 image missing
1024×768 PNG in the 1024 slot	0	none	1024 image missing
Only [email protected]	0	none	1 image (1024)
Fully opaque PNGs (no alpha)	0	none	full icon
Extra README.txt in the folder	0	none	ignored, full icon
Existing .icns at the output path	0	none	overwritten
Folder without .iconset	1	Invalid Iconset. (twice)	nothing
Names like hexchat_16x16.png	1	Failed to generate ICNS.	nothing
Names starting Icon_ (capital I)	1	Failed to generate ICNS.	nothing
icon_1024x1024.png alone	1	Failed to generate ICNS.	nothing
Empty .iconset	1	Failed to generate ICNS.	nothing
-o without .icns extension	1	The file extension must equal icns.	nothing

The extra chunk in a correct build is a 318-byte info record, a keyed-archive plist holding the name "icon". iconutil adds it every time. The 16 and 32 pixel images are stored as raw ARGB data, not PNG.

Eight Stack Overflow questions, checked against 26.4.1

I read the eight Stack Overflow questions about iconutil errors and creating .icns files, asked from 2012 to 2017, through the Stack Exchange API. Three came down to file naming and one to pixel sizes:

• "Invalid iconset" (2013, score 20): the folder lacked the .iconset extension. That still holds today, and the message prints twice.
• "Failed to generate ICNS" (2015, score 15): files were named hexchat_16x16.png. Still fails, exit 1.
• "Iconutil giving error" (2012): the @2x files were the same pixel size as the 1x files, and the .icns came out with 8 images instead of 10. That matches the grid above. A 128-pixel file named @2x has no slot.

Two claims didn't reproduce on 26.4.1. "Unsupported image format" (2016) says iconutil on OS X 10.11 rejected PNGs without an alpha channel. A fully opaque set built here with no error. "iconutil not working on macOS High Sierra" (2017) has an accepted answer saying 1000×1000 "worked" on Sierra and failed on High Sierra. On 26.4.1 it neither works nor fails. The file is left out, and the run reports success.

Can sips convert PNG to ICNS directly?

Partly. sips -s format icns in.png --out out.icns works only at 16, 32, 48, 128, 256 and 512 pixels. I tried 13 sizes. At 1024, the size an app icon needs most, it fails with Error 13: an unknown error occurred and an "Unable to write image" line naming a temp file, exit 13. 64, 100, 200, 300, 511, 513 and 1023 fail the same way. When it does work, you get a single-size icon: the 512 run produced one ic09 image plus a table of contents, and the 16, 32 and 48 runs wrote the old pre-Retina is32/il32/ih32 formats with separate masks. That's fine for a folder icon on a non-Retina screen, but not for an app. Use sips to resize and iconutil to pack. (My sips WebP format count found 22 formats sips can write. ICNS is one of them, with this size limit.)

What Apple ships in Tahoe: .icns capped at 256

Tahoe app icons come from Icon Composer's .icon files. Apple's Icon Composer documentation says the Xcode project file "replaces any existing icon asset catalog" and that Xcode generates images for older releases at build time. I wanted to see what that leaves in a built app, so I opened all 65 apps in /System/Applications and /System/Applications/Utilities.

All 65 still ship a .icns file and set both CFBundleIconFile and CFBundleIconName. All 65 also ship an Assets.car. But every one of the 65 .icns files has exactly four images: ic04, ic11, ic07 and ic13, which are 16, 32 (16@2x), 128 and 256 (128@2x) pixels. They range from 1,992 to 96,442 bytes. The full-size icon lives only in the asset catalog. iconutil can pull it out, which the man page mentions in one sentence:

iconutil -c icns /System/Applications/Calculator.app/Contents/Resources/Assets.car AppIcon -o calc.icns
# 10 images up to 1024 px, 864,499 bytes (the bundled AppIcon.icns is 50,462)

A wrong icon name prints Icon resource not found in asset catalog with name 'NoSuchIcon'. and exits 1. If you copy a system app's .icns to use as a starting point, you get a 256-pixel ceiling. Extract from Assets.car instead.

For your own app on Tahoe, a hand-built .icns still works as a file and folder icon, and as the app icon on older macOS versions. Apple's developer forum thread on supporting older versions with Icon Composer shows the opposite problem: the .icon and the older .icns don't always land in the bundle the way developers expect. I didn't build an Icon Composer project, so I can't say which icon Finder picks when both are present.

Where this fits in my setup

I don't ship a Mac app. I got here because I keep testing the command-line tools that come with macOS, as in the plutil tests and the hdiutil convert crash count. iconutil follows the same pattern as those two: some failures exit 0. The fix is to check the output, not the exit code. For a .icns, that means expanding it again and counting files. The same reasoning is behind how I build the site's card images with Pillow. Each output is checked after it is written, because the build step itself has failed without saying so.

FAQ

How do I convert a PNG to ICNS on Mac?

Make a folder ending in .iconset, use sips -z to write ten resized copies of a 1024×1024 PNG named icon_16x16.png, [email protected] and so on up to [email protected], then run iconutil -c icns on the folder. Check the result with iconutil -c iconset on the new .icns: a complete icon expands back into 10 PNG files.

Why does iconutil say "Failed to generate ICNS"?

On macOS 26.4.1 that error means no usable image was found. The usual causes are file names that don't start with lowercase icon_, a folder with no valid files, or a file whose pixel size doesn't match any slot, such as 1000×1000 or a 128-pixel file named @2x. If the folder also contains valid files, the bad ones are dropped without an error instead.

Can sips convert PNG to ICNS?

Only at certain sizes. sips -s format icns worked for 16, 32, 48, 128, 256 and 512-pixel PNGs and produced a single-size icon. At 1024 pixels, and at sizes like 64 or 1000, it failed with "Error 13: an unknown error occurred". For a full app icon, use sips to resize and iconutil to build the .icns.

Method: all tests ran on 2026-10-08 between 21:00 and 21:30 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253, /usr/bin/iconutil 136,464 bytes, /usr/bin/sips 505,616 bytes) in a scratch folder. The source image was Calculator's 1024-pixel icon extracted from its Assets.car, resized with sips; no icon was published or redistributed. Chunk types and sizes come from a small Python reader for the .icns header. The 80-run grid used one file per iconset; the 1000-pixel, JPEG and non-square cases were tested inside an otherwise complete set. The collision result is from two runs only. The 65-app check read each app's Info.plist and parsed the .icns it names. Stack Overflow questions are the eight error and how-to threads among the API search results for "iconutil", read with their top answers. I did not test Icon Composer, Xcode builds, or macOS versions other than 26.4.1.