View source for Apple Icon Image format

{{Short description|none}}
{{Use mdy dates|date=October 2013}}
{{Infobox file format
| name = Apple Icon Image
| icon = [[File:icns.png|ICNS icon.]]
| extension = {{mono|.icns}}
| mime = 
| type code = {{mono|icns}}
| uniform type = com.apple.icns
| owner = [[Apple Inc.]]
| genre = [[icon (computing)|Icon]] [[graphics file format|file format]]
| container for = 
| contained by = 
| extended from = 
| extended to = 
| magic = {{code|69 63 6e 73}}
}}
The '''Apple Icon Image format''' (.icns) is an [[icon (computing)|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 [[bit|1-]] and [[8-bit]] [[Alpha compositing|alpha channel]]s 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.<ref>{{cite web|title=Human Interface Guidelines|url=https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/app-icon/|url-status=live|access-date=April 10, 2021|publisher=Apple Inc.|archive-url=https://web.archive.org/web/20180618155438/https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/app-icon/ |archive-date=June 18, 2018 }}</ref>

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

=== Header ===
{| class="wikitable"
|-
! 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 ===
{| class="wikitable"
|-
! 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 ===
{| class="wikitable sortable" style="clear:right"
|-
! [[OSType]]
! Length (bytes)
! Size (pixels)
! Supported OS Version
! class="unsortable"|Description
|-
| {{mono|ICON}}
| 128
| 32×32
| 1.0
| 1-bit mono icon
|-
| {{mono|ICN#}}
| 256
| 32×32
| 6.0
| 1-bit mono icon with 1-bit mask
|-
| {{mono|icm#}}
| 48
| 16×12
| 6.0
| 1 bit mono icon with 1-bit mask
|-
| {{mono|icm4}}
| 96
| 16×12
| 7.0
| 4 bit icon
|-
| {{mono|icm8}}
| 192
| 16×12
| 7.0
| 8 bit icon
|-
| {{mono|ics#}}
| 64
| 16×16
| 6.0
| 1-bit mono icon with 1-bit mask
|-
| {{mono|ics4}}
| 128
| 16×16
| 7.0
| 4-bit icon
|-
| {{mono|ics8}}
| 256
| 16×16
| 7.0
| 8 bit icon
|-
| {{mono|is32}}
| varies{{sup|1}} (768)
| 16×16
| 8.5
| 24-bit RGB icon
|-
| {{mono|s8mk}}
| 256
| 16×16
| 8.5
| 8-bit mask
|-
| {{mono|icl4}}
| 512
| 32×32
| 7.0
| 4-bit icon
|-
| {{mono|icl8}}
| 1024
| 32×32
| 7.0
| 8-bit icon
|-
| {{mono|il32}}
| varies{{sup|1}} (3072)
| 32×32
| 8.5
| 24-bit RGB icon
|-
| {{mono|l8mk}}
| 1024
| 32×32
| 8.5
| 8-bit mask
|-
| {{mono|ich#}}
| 576
| 48×48
| 8.5
| 1-bit mono icon with 1-bit mask
|-
| {{mono|ich4}}
| 1152
| 48×48
| 8.5
| 4-bit icon
|-
| {{mono|ich8}}
| 2304
| 48×48
| 8.5
| 8-bit icon
|-
| {{mono|ih32}}
| varies{{sup|1}} (6912)
| 48×48
| 8.5
| 24-bit RGB icon
|-
| {{mono|h8mk}}
| 2304
| 48×48
| 8.5
| 8-bit mask
|-
| {{mono|it32}}
| varies{{sup|1}} (49152 + 4){{sup|2}}
| 128×128
| 10.0
| 24-bit RGB icon
|-
| {{mono|t8mk}}
| 16384
| 128×128
| 10.0
| 8-bit mask
|-
| {{mono|icp4}}
| varies
| 16x16
| 10.7
| [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format or 24-bit RGB icon<ref name="rgb-icp4">{{citation|version=macOS 11|title=System icon: /System/Library/CoreServices/Applications/Screen Sharing.app/Contents/Resources/InternetLocationVNC.icns}}</ref>
|-
| {{mono|icp5}}
| varies
| 32x32
| 10.7
| [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format or 24-bit RGB icon<ref name="rgb-icp4" />
|-
| {{mono|icp6}}
| varies
| 48x48
| 10.7
| [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format
|-
| {{mono|ic07}}
| varies
| 128x128
| 10.7
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format
|-
| {{mono|ic08}}
| varies
| 256x256
| 10.5
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format
|-
| {{mono|ic09}}
| varies
| 512x512
| 10.5
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format
|-
| {{mono|ic10}}
| varies
| 1024x1024
| 10.7
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (512x512@2x "retina" in 10.8)
|-
| {{mono|ic11}}
| varies
| 32x32
| 10.8
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (16x16@2x "retina")
|-
| {{mono|ic12}}
| varies
| 64x64
| 10.8
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (32x32@2x "retina")
|-
| {{mono|ic13}}
| varies
| 256x256
| 10.8
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (128x128@2x "retina")
|-
| {{mono|ic14}}
| varies
| 512x512
| 10.8
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (256x256@2x "retina")
|-
| {{mono|ic04}}
| varies{{sup|1}} (1024)
| 16x16
|
| ARGB or [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format
|-
| {{mono|ic05}}
| varies{{sup|1}} (4096)
| 32x32
|
| ARGB or [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format (16x16@2x "retina")
|-
| {{mono|icsb}}
| varies{{sup|1}} (1296)
| 18x18
|
| ARGB or [[JPEG 2000]]{{sup|†}} or [[Portable Network Graphics|PNG]]{{sup|†}} format
|-
| {{mono|icsB}}
| varies
| 36x36
|
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (18x18@2x "retina")
|-
| {{mono|sb24}}
| varies
| 24x24
|
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format
|-
| {{mono|SB24}}
| varies
| 48x48
|
| [[JPEG 2000]] or [[Portable Network Graphics|PNG]] format (24x24@2x "retina")
|}

* {{sup|1.}} The value inside the parenthesis is the uncompressed length for ARGB and 24-bit RGB icons.
* {{sup|2.}} {{mono|it32}} data always starts with a header of four zero-bytes (tested all icns files in macOS 10.15.7 and macOS 11). Usage unknown, the four zero-bytes can be any value and are quietly ignored.
* {{sup|†.}} These formats are supported in standalone icns files but do not display properly if used as application icon inside a {{mono|.app}} package.

==== Image data format ====
* Mono icons with alpha mask can display three colors: white, black, and transparent.
* The 4-bit an 8-bit icons use a fixed color palette with 16 colors and 256 colors, respectively.
* The 24-bit RGB format consists of the three compressed channels tightly packed (see [[#Compression|Compression]]). The {{mono|it32}} icon must start with a four-byte header, see footnote above.
* The ARGB format consists of the ascii values for 'ARGB' and the four compressed channels tightly packed (see [[#Compression|Compression]]).

==== Compatibility ====
* the ARGB fields also accept files in PNG format – but not vice versa, you can not put ARGB images in any of the PNG-only fields (tested on macOS 11).
* ARGB images are only supported in macOS 11 and newer – macOS 10.15.7 does not display ARGB images. Yet, even the ARGB keys can be displayed on macOS 10.15 if you set a JPEG 2000 or PNG image (see footnote on usage in app packages above).
* The 24-bit RGB icons ({{mono|is32}}, {{mono|il32}}, {{mono|ih32}}, {{mono|it32}}) also allow images in JPEG 2000 and PNG format (tested on macOS 10.15.7 and macOS 11).
* The support for newer image types seems to be introduced later than the key field (see previous two points). Therefore, the supported OS version may not be accurate or adjusted based on file format.

=== Other types ===
{| class="wikitable sortable"
|-
! [[OSType]]
! class="unsortable"|Description
|-
| {{code|'TOC '}}
| "Table of Contents" a list of all image types in the file, and their sizes (added in [[Mac OS X Lion|Mac OS X 10.7]]).
A TOC is written out as an identifier (4 bytes) and size (4 bytes). Each subsequent record (8 bytes each) maps
to the icon formats found in the file. The data isn't included in this phase.
|-
| {{code|'icnV'}}
| 4-byte big endian float - equal to the bundle version number of Icon Composer.app that created the icon
|-
| {{code|'name'}}
| Usage unknown (all tested files use either "icon"<ref>{{citation|version=macOS 10.15.7|title=System icon: /System/Library/PrivateFrameworks/PassKitCore.framework/Versions/A/Resources/GenericIcon.icns}}</ref> or "template"<ref>{{citation|version=macOS 10.15.7|title=System icon: /System/Library/PrivateFrameworks/ConsoleKit.framework/Versions/A/Resources/SidebariPhone.icns}}</ref>).
|-
| {{code|'info'}}
| Info binary [[Property list|plist]]. Usage unknown (only name field seems to be used).
|-
| {{code|'sbtp'}}
| Nested "template" icns file. Usage unknown.
|-
| {{code|'slct'}}
| Nested "selected" icns file. Usage unknown.
|-
| {{nowrap|{{code|FD D9 2F A8}}}}
| Nested "dark" icns file. Allows automatic icon switching in [[Dark mode]]. (added in [[macOS Mojave|macOS 10.14]]).
''Note: The contents of this record is a full .icns file with multiple formats. If the record bytes are written out''
to disk, the icns file header and file size are still required to see the full dark mode icon. 
|}

* The table of contents is a list of all contained types (4 byte type-name + 4 byte length).
* The data for all nested icns files does not contain the icns file-header. So, if you want to save the data to a file you have to prepend the [[#Header|icns header]].

== 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).<ref>[https://github.com/fiahfy/icns.git Fiahfy ICNS Repo]</ref>

'''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 ==
{| style="clear:right;float:right;margin:0 0 0 0.5em" class="wikitable"
|-
!lead<br />{{small|value}}
!tail<br />{{small|bytes}}
!result<br />{{small|uncompressed}}
|-
|{{small|{{samp|&nbsp;&nbsp;0}}...{{samp|127}}}}
|{{small|{{samp|1}}...{{samp|128}}}}
|{{small|{{samp|1}}...{{samp|128}}}} bytes
|-
|{{small|{{samp|128}}...{{samp|255}}}}
|{{small|{{samp|1}}}} byte
|{{small|{{samp|3}}...{{samp|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 ({{mono|is32}}, {{mono|il32}}, {{mono|ih32}}, {{mono|it32}}, {{mono|icp4}}, {{mono|icp5}}) and ARGB ({{mono|ic04}}, {{mono|ic05}}, {{mono|icsb}}) pixel data are compressed (per channel) with a format similar to [[PackBits]].<ref name="macdisk">[http://www.macdisk.com/maciconen.php#RLE Macintosh Icons]</ref>
Some sources mention that the OS supports both compressed or uncompressed data chunks.{{cn|date=August 2021}} 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: [https://github.com/nyteshade/ByteRunLengthCoder ByteRunLengthCoder]

The following [[pseudocode]] decompresses the data:
{{pre|1=
'''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: {{code|02 01 02 02 80 03 81 04 82 05}} should decompress to {{code|01 02 02 03 03 03 04 04 04 04 05 05 05 05 05}}

The following [[pseudocode]] compresses the data:
{{pre|1=
'''function''' Encode(input data)
  '''Initialize''' output '''as''' an '''empty array'''
  '''Set''' index '''to''' 0

  '''While''' index {{dfn|<|is less than}} the count of data
    '''Initialize''' sequence '''as''' an '''empty array'''
    '''Set''' count '''to''' 0

    ''// Unique sequence''
    '''While''' count {{dfn|≤|is less than or equal to}} 0x7F '''and''' index {{dfn|<|is less than}} count of data
      '''If''' index + 2 {{dfn|<|is less than}} count of data '''and''' data{{tooltip|[index]|at index}} {{dfn|{{=}}|is equal to}} data{{tooltip|[index+1]|at index + 1}} '''and''' data{{tooltip|[index]|at index}} {{dfn|{{=}}|is equal to}} data{{tooltip|[index+2]|at index + 2}}
        '''Break''' the '''loop'''  ''// Start of a repeating sequence''
      '''End''' '''If'''

      '''Append''' data{{tooltip|[index]|at 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 {{dfn|≥|is greater than or equal to}} count of data
      '''Break''' the '''loop'''
    '''End''' '''If'''

    ''// Repeating sequence''
    '''Set''' repeatedByte '''to''' data{{tooltip|[index]|at index}}
    '''Set''' count '''to''' 0
    '''While''' count {{dfn|≤|is less than or equal to}} 0x7F '''and''' index {{dfn|≤|is less than count of}} data '''and''' data{{tooltip|[index]|at index}} {{dfn|{{=}}|is equal to}} repeatedByte
      Increment index
      Increment count
    '''End''' '''While'''

    '''If''' count {{dfn|≥|is greater than or equal to}} 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: {{code|01 02 02 03 03 03 04 04 04 04 05 05 05 05 05}} should compress to {{code|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:

# Setting {{mono|is32+ics8}} or {{mono|ih32+ich8}} will display a proper icon. But setting {{mono|il32+icl8}} ignores the transparency mask and displays an icon without transparency.
# 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|Compression]]). Potentially, up to 130 pixels can lack the blue channel value. <br> 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:
#* {{code|69636E73 00000024 69633034 0000001C 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF}} 
#* {{code|69636E73 00000025 69633034 0000001D 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF 00}}
# macOS 10.15.7 (likely earlier) and later versions have an issue displaying PNG and JPEG 2000 icons for the keys {{mono|icp4}} (16x16), {{mono|icp5}} (32x32), and {{mono|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 {{mono|ic04}} and {{mono|ic05}} (macOS 11+) or the old 24-bit RGB + alpha mask format. Use the latter with the old keys {{mono|is32+s8mk}} and {{mono|il32+l8mk}}, or with the newer keys {{mono|icp4+s8mk}} and {{mono|icp5+l8mk}} (writing RGB data into PNG fields<ref name="rgb-icp4" />). 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 {{mono|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 apps can open <kbd>*.icns</kbd> files including [[Preview (macOS)|Preview]] and [[GTK+]], with some offering the ability to convert <kbd>*.icns</kbd> to and from [[Portable Network Graphics|PNG]] as well.<ref>{{cite web|url=http://icns.sourceforge.net/|title=libicns|publisher=[[SourceForge]] project icns|date=2009|access-date=2016-08-18}}</ref><ref>{{cite web|url=https://github.com/moinism/png2icns|title=png2icns|publisher=Moin Uddin|date=2016|access-date=2017-05-25}}</ref><ref>{{cite web|url=http://ezix.org/project/wiki/MacOSXIcons|title=Mac OS X icons for GTK+|author=Lyonel Vincent|date=2007|access-date=2016-08-18}}</ref> Former tools specializing in icon file support include [[Apple Developer Tools#Icon Composer|Icon Composer]] and [[Apple Developer Tools#icns Browser|icns Browser]] from Apple, [[IconBuilder]] from [[The Iconfactory]], and [[CandyBar]] from [[Panic Inc.|Panic]].

MacOS offers the built-in <code>iconutil</code> command line tool to pack and unpack <kbd>*.icns</kbd> files.<ref>{{Cite web |title=Optimizing for High Resolution |url=https://developer.apple.com/library/archive/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Optimizing/Optimizing.html |access-date=2025-03-22 |website=developer.apple.com}}</ref>

==See also==
* [[ICO (icon image file format)|ICO format]] on [[Microsoft Windows|Windows]]
* [[X PixMap]] format for [[X Window System|X11]]

== References ==
<references/>

==External links==
* [http://iconfamily.sourceforge.net IconFamily] (last update 2013) – Open source Objective C class to read and write Apple icns files
* [https://github.com/sveinbjornt/osxiconutils osxiconutils] (not maintained) – Command line tools to work with Apple icns files
* [https://github.com/relikd/icnsutil icnsutil] – Python library to read and write icns files
* [https://lib.rs/crates/icns icns] - Rust crate to read and write icns files
* [https://github.com/avl7771/createicns createicns] - C library to read and write icns files
* [https://github.com/nyteshade/icon_record_extractor icon_records_extractor] - C library to extract all icns records as their own icons include dark mode icns.

{{Mac OS X}}
{{Graphics file formats}}

[[Category:Graphics file formats]]
[[Category:MacOS]]
[[Category:Computer icons]]