Apple Icon Image

Filename extension	.icns
Internet media type	image/x-icns
Type code	icns
Uniform Type Identifier (UTI)	com.apple.icns
Magic number	69 63 6e 73
Developed by	Apple Inc.
Type of format	Icon file format

The Apple Icon Image format (.icns) 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.

Non-PNG / JPEG2000 Element Types

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).^[5]

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.

Compression

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.^[6] 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:

'''While''' there '''is''' 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

The following pseudocode compresses the data:

'''function''' Encode(input data)
  '''Initialize''' output '''as''' an '''empty array'''
  '''Set''' index '''to''' 0

  '''While''' index <dfn   class="explain " ><span title="is less than"><</span></dfn> the count of data
    '''Initialize''' sequence '''as''' an '''empty array'''
    '''Set''' count '''to''' 0

    ''// Unique sequence''
    '''While''' count <dfn   class="explain " ><span title="is less than or equal to">≤</span></dfn> 0x7F '''and''' index <dfn   class="explain " ><span title="is less than"><</span></dfn> count of data
      '''If''' index + 2 <dfn   class="explain " ><span title="is less than"><</span></dfn> count of data '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index">[index]</span> <dfn   class="explain " ><span title="is equal to">=</span></dfn> data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index + 1">[index+1]</span> '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index">[index]</span> <dfn   class="explain " ><span title="is equal to">=</span></dfn> data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index + 2">[index+2]</span>
        '''Break''' the '''loop'''  ''// Start of a repeating sequence''
      '''End''' '''If'''

      '''Append''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index">[index]</span> '''to''' sequence
      Increment index
      Increment count
    '''End''' '''While'''

    '''If''' sequence '''is not empty'''
      '''Append''' (count - 1) '''to''' output
      '''Append''' all items '''in''' sequence '''to''' output
    '''End''' '''If'''

    '''If''' index <dfn   class="explain " ><span title="is greater than or equal to">≥</span></dfn> count of data
      '''Break''' the '''loop'''
    '''End''' '''If'''

    ''// Repeating sequence''
    '''Set''' repeatedByte '''to''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index">[index]</span>
    '''Set''' count '''to''' 0
    '''While''' count <dfn   class="explain " ><span title="is less than or equal to">≤</span></dfn> 0x7F '''and''' index <dfn   class="explain " ><span title="is less than count of">≤</span></dfn> data '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted "   title="at index">[index]</span> <dfn   class="explain " ><span title="is equal to">=</span></dfn> repeatedByte
      Increment index
      Increment count
    '''End''' '''While'''

    '''If''' count <dfn   class="explain " ><span title="is greater than or equal to">≥</span></dfn> 3
      '''Append''' (0x80 + count - 3) '''to''' output
      '''Append''' repeatedByte '''to''' output
    '''Else'''  ''// Less than 3 repeating bytes''
      '''Append''' (count - 1) '''to''' output
      '''Repeat''' (count) times
        '''Append''' repeatedByte '''to''' output
      '''End''' '''Repeat'''
    '''End''' '''If'''
  '''End''' '''While'''

  '''Return''' output
'''End''' '''function'''

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

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.^[7][8] GTK+ can load *.icns resources since 2007.^[9] Other tools supporting the format include the Apple Icon Composer and icns Browser, The Iconfactory, and IconBuilder.
MacOS offers the built-in iconutil command line tool to pack and unpack *.icns files.

See also

• ICO format on Windows
• X PixMap format for X11

References

External links

• IconFamily (last update 2013) – Open source Objective C class to read and write Apple icns files
• osxiconutils (not maintained) – Command line tools to work with Apple icns files
• icnsutil – Python library to read and write icns files
• icns - Rust crate to read and write icns files
• createicns - C library to read and write icns files
• icon_records_extractor - C library to extract all icns records as their own icons include dark mode icns.