Apple Icon Image
ICNS icon.
Filename extension
.icns
Internet media typeimage/x-icns
Type codeicns
Uniform Type Identifier (UTI)com.apple.icns
Magic number69 63 6e 73
Developed byApple Inc.
Type of formatIcon file format

The Apple Icon Image format is an icon format used in Apple Inc.'s macOS. It supports icons of 16 × 16, 32 × 32, 48 × 48, 128 × 128, 256 × 256, 512 × 512 points at 1x and 2x scale, with both 1- and 8-bit alpha channels and multiple image states (example: open and closed folders). The fixed-size icons can be scaled by the operating system and displayed at any intermediate size.

As of macOS 11, asset catalogs are the preferred file format for macOS custom icons instead.[1]

File structure

The file format consists of an 8 byte header, followed by any number of icons.

Header

Offset Size Purpose
0 4 Magic literal, must be "icns" (0x69, 0x63, 0x6e, 0x73)
4 4 Length of file, in bytes, msb first

Icon data

Offset Size Purpose
0 4 Icon type, see OSType below.
4 4 Length of data, in bytes (including type and length), msb first
8 Variable Icon data

Icon types

OSType Length (bytes) Size (pixels) Supported OS Version Description
ICON 128 32×32 1.0 1-bit mono icon
ICN# 256 32×32 6.0 1-bit mono icon with 1-bit mask
icm# 48 16×12 6.0 1 bit mono icon with 1-bit mask
icm4 96 16×12 7.0 4 bit icon
icm8 192 16×12 7.0 8 bit icon
ics# 64 16×16 6.0 1-bit mono icon with 1-bit mask
ics4 128 16×16 7.0 4-bit icon
ics8 256 16×16 7.0 8 bit icon
is32 varies1 (768) 16×16 8.5 24-bit RGB icon
s8mk 256 16×16 8.5 8-bit mask
icl4 512 32×32 7.0 4-bit icon
icl8 1024 32×32 7.0 8-bit icon
il32 varies1 (3072) 32×32 8.5 24-bit RGB icon
l8mk 1024 32×32 8.5 8-bit mask
ich# 576 48×48 8.5 1-bit mono icon with 1-bit mask
ich4 1152 48×48 8.5 4-bit icon
ich8 2304 48×48 8.5 8-bit icon
ih32 varies1 (6912) 48×48 8.5 24-bit RGB icon
h8mk 2304 48×48 8.5 8-bit mask
it32 varies1 (49152 + 4)2 128×128 10.0 24-bit RGB icon
t8mk 16384 128×128 10.0 8-bit mask
icp4 varies 16x16 10.7 JPEG 2000 or PNG format or 24-bit RGB icon[2]
icp5 varies 32x32 10.7 JPEG 2000 or PNG format or 24-bit RGB icon[2]
icp6 varies 48x48 10.7 JPEG 2000 or PNG format
ic07 varies 128x128 10.7 JPEG 2000 or PNG format
ic08 varies 256x256 10.5 JPEG 2000 or PNG format
ic09 varies 512x512 10.5 JPEG 2000 or PNG format
ic10 varies 1024x1024 10.7 JPEG 2000 or PNG format (512x512@2x "retina" in 10.8)
ic11 varies 32x32 10.8 JPEG 2000 or PNG format (16x16@2x "retina")
ic12 varies 64x64 10.8 JPEG 2000 or PNG format (32x32@2x "retina")
ic13 varies 256x256 10.8 JPEG 2000 or PNG format (128x128@2x "retina")
ic14 varies 512x512 10.8 JPEG 2000 or PNG format (256x256@2x "retina")
ic04 varies1 (1024) 16x16 ARGB or JPEG 2000 or PNG format
ic05 varies1 (4096) 32x32 ARGB or JPEG 2000 or PNG format (16x16@2x "retina")
icsb varies1 (1296) 18x18 ARGB or JPEG 2000 or PNG format
icsB varies 36x36 JPEG 2000 or PNG format (18x18@2x "retina")
sb24 varies 24x24 JPEG 2000 or PNG format
SB24 varies 48x48 JPEG 2000 or PNG format (24x24@2x "retina")

Image data format

Compatibility

Other types

OSType Description
'TOC ' "Table of Contents" a list of all image types in the file, and their sizes (added in Mac OS X 10.7)
'icnV' 4-byte big endian float - equal to the bundle version number of Icon Composer.app that created the icon
'name' Usage unknown (all tested files use either "icon"[3] or "template"[4]).
'info' Info binary plist. Usage unknown (only name field seems to be used).
'sbtp' Nested "template" icns file. Usage unknown.
'slct' Nested "selected" icns file. Usage unknown.
FD D9 2F A8 Nested "dark" icns file. Allows automatic icon switching in Dark mode. (added in macOS 10.14)

Compression

lead
value
tail
bytes
result
uncompressed
  0...127 1...128 1...128 bytes
128...255 1 byte 3...130 copies

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.[5] Some sources mention that the OS supports both compressed or uncompressed data chunks.[citation needed] 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).

The following pseudocode decompresses the data:

While there's compressed data:
    Read one byte as an unsigned number N
    If N < 0x80:
        Output the next (N + 1) bytes
    Else:
        Output the next byte (N - 0x80 + 3) times

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

Known issues

As of macOS 11, there are certain issues / bugs with the file format:

  1. Setting is32+ics8 or ih32+ich8 will display a proper icon. But setting il32+icl8 ignores the transparency mask and displays an icon without transparency.
  2. Compressed ARGB data is not interpreted correctly. The last value of the blue channel (aka. the very last value) is ignored and treated as if it were all zero-bytes. Usually this is no issue since most icons will have transparency at the bottom right corner anyway. However, it can become an issue if the last value is a repeating byte (see Compression). Potentially, up to 130 pixels can lack the blue channel value.
    A workaround is to append an additional byte at the end which is interpreted as a control character without following data. You can compare the difference with these two examples:
    • 69636E73 00000024 69633034 0000001C 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF
    • 69636E73 00000025 69633034 0000001D 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF 00
  3. macOS 10.15.7 (likely earlier) and later versions have an issue displaying PNG and JPEG 2000 icons for the keys icp4 (16x16), icp5 (32x32), and icp6 (64x64). The keys work fine in a standalone icns file but if used in an application, the icons are displayed completely scrambled. Either use the new ARGB format ic04 and ic05 (macOS 11+) or the old 24-bit RGB + alpha mask format. Use the latter with the old keys is32+s8mk and il32+l8mk, or with the newer keys icp4+s8mk and icp5+l8mk (writing RGB data into PNG fields[2]). If using ARGB image data, make sure to provide alternative formats for macOS 10.15 and earlier. This issue is especially tricky to detect if you provide both, 16x16 and 16x16@2x icons, because if you connect your Mac to a non-retina monitor, the non-retina 16x16 icon will be used and thus the icon will be displayed scrambled. The icp6 field does not seem to be used in application icons and can safely be ignored. Additionally, if you don't provide the smaller icon sizes at all the bug will also manifest when the OS scales down your larger PNG/JPEG 2000 icons, so make sure to render smaller sizes and include them.

Support

Various image viewers can load *.icns files, and free and open source converters from or to PNG also exist.[6][7] GTK+ can load *.icns resources since 2007.[8] Other tools supporting the format include the Apple Icon Composer and icns Browser, The Iconfactory, and IconBuilder.
MacOS[clarification needed] offers the built-in iconutil command line tool to pack and unpack *.icns files.

See also

References

  1. ^ "Human Interface Guidelines". Apple Inc. Archived from the original on June 18, 2018. Retrieved April 10, 2021.
  2. ^ a b c System icon: /System/Library/CoreServices/Applications/Screen Sharing.app/Contents/Resources/InternetLocationVNC.icns, macOS 11
  3. ^ System icon: /System/Library/PrivateFrameworks/PassKitCore.framework/Versions/A/Resources/GenericIcon.icns, macOS 10.15.7
  4. ^ System icon: /System/Library/PrivateFrameworks/ConsoleKit.framework/Versions/A/Resources/SidebariPhone.icns, macOS 10.15.7
  5. ^ Macintosh Icons
  6. ^ "libicns". SourceForge project icns. 2009. Retrieved August 18, 2016.
  7. ^ "png2icns". Moin Uddin. 2016. Retrieved May 25, 2017.
  8. ^ Lyonel Vincent (2007). "Mac OS X icons for GTK+". Retrieved August 18, 2016.