The file format consists of an 8 byte header, followed by any number of icons.
A TOC is written out as an identifier (4 bytes) and size (4 bytes). Each subsequent record (8 bytes each) mapsto the icon formats found in the file. The data isn't included in this phase.
Note: The contents of this record is a full .icns file with multiple formats. If the record bytes are written outto disk, the icns file header and file size are still required to see the full dark mode icon.
Element types that deal with ARGB (32-bit) or RGB (24-bit) image formats require different types of headers before the binary data. It is important to note that this header is part of the image data and is not the 4-byte big endian icon element type value (e.g. ic04 or ic05).6
ARGB Elements ARGB images must have their binary portion of the image data preceded by the four byte 'ARGB' header. After that, instead of each pixel with each of its four channels stored together (e.g. ARGBARGBARGB), an image with three pixels would be stored in individual channels of pixel data (e.g. AAARRRGGGBBB). In addition, each channel of pixel data needs to be encoded as mentioned below.
RGB Elements RGB images have their binary portion of the image data preceded by four zero byte characters only when the element type is 'it32'. In all other cases, no header is needed. Channel data is separated as with the ARGB binary data (e.g. RRRGGGBBB instead of RGBRGBRGB). Each channel must also be encoded as mentioned below.
Mask Elements Mask elements are not encoded like ARGB and RGB image color channel data. The data is the same as that of an ARGB image except only the alpha channel data is provided. So for an image that has two pixels, ARGBARGB, the mask data is AA.
Over time the format has been improved and there is support for compression of some parts of the pixel data. The 24-bit RGB (is32, il32, ih32, it32, icp4, icp5) and ARGB (ic04, ic05, icsb) pixel data are compressed (per channel) with a format similar to PackBits.7 Some sources mention that the OS supports both compressed or uncompressed data chunks. However, manually crafting icns files with uncompressed 24-bit RGB or ARGB images will not display properly – at least on newer macOS releases (tested on macOS 11).
Here is a GitHub repo with some swift code that appears to pass the test for both encoding and decoding as described here: ByteRunLengthCoder
The following pseudocode decompresses the data:
Example: 02 01 02 02 80 03 81 04 82 05 should decompress to 01 02 02 03 03 03 04 04 04 04 05 05 05 05 05
The following pseudocode compresses the data:
Example: 01 02 02 03 03 03 04 04 04 04 05 05 05 05 05 should compress to 02 01 02 02 80 03 81 04 82 05
As of macOS 11, there are certain issues / bugs with the file format:
Various apps can open *.icns files including Preview and GTK+, with some offering the ability to convert *.icns to and from PNG as well.91011 Former tools specializing in icon file support include Icon Composer and icns Browser from Apple, IconBuilder from The Iconfactory, and CandyBar from Panic.
MacOS offers the built-in iconutil command line tool to pack and unpack *.icns files.12
"Human Interface Guidelines". Apple Inc. Archived from the original on June 18, 2018. Retrieved April 10, 2021. https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/app-icon/ ↩
System icon: /System/Library/CoreServices/Applications/Screen Sharing.app/Contents/Resources/InternetLocationVNC.icns, macOS 11 ↩
System icon: /System/Library/PrivateFrameworks/PassKitCore.framework/Versions/A/Resources/GenericIcon.icns, macOS 10.15.7 ↩
System icon: /System/Library/PrivateFrameworks/ConsoleKit.framework/Versions/A/Resources/SidebariPhone.icns, macOS 10.15.7 ↩
Fiahfy ICNS Repo https://github.com/fiahfy/icns.git ↩
Macintosh Icons http://www.macdisk.com/maciconen.php#RLE ↩
"libicns". SourceForge project icns. 2009. Retrieved August 18, 2016. http://icns.sourceforge.net/ ↩
"png2icns". Moin Uddin. 2016. Retrieved May 25, 2017. https://github.com/moinism/png2icns ↩
Lyonel Vincent (2007). "Mac OS X icons for GTK+". Retrieved August 18, 2016. http://ezix.org/project/wiki/MacOSXIcons ↩
"Optimizing for High Resolution". developer.apple.com. Retrieved March 22, 2025. https://developer.apple.com/library/archive/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Optimizing/Optimizing.html ↩