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.

File structure

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

Header

Icon data

Icon types

Image data format

Compatibility

Other types

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). 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. 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 the count of data Initialize sequence as an empty array Set count to 0 // Unique sequence While count 0x7F and index count of data If index + 2 count of data and data[index] data[index+1] and data[index] data[index+2] Break the loop // Start of a repeating sequence End If Append data[index] 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 count of data Break the loop End If // Repeating sequence Set repeatedByte to data[index] Set count to 0 While count 0x7F and index data and data[index] repeatedByte Increment index Increment count End While If count 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:

Support

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