Hubbry Logo
Apple Icon Image formatApple Icon Image formatMain
Open search
Apple Icon Image format
Community hub
Apple Icon Image format
logo
7 pages, 0 posts
0 subscribers
Be the first to start a discussion here.
Be the first to start a discussion here.
Apple Icon Image format
Apple Icon Image format
Apple Icon Image format
View on Wikipedia
from Wikipedia

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 (.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.[1]

File structure

[edit]

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

[edit]
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

[edit]
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

[edit]
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")
  • 1. The value inside the parenthesis is the uncompressed length for ARGB and 24-bit RGB icons.
  • 2. 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.
  • †. These formats are supported in standalone icns files but do not display properly if used as application icon inside a .app package.

Image data format

[edit]
  • 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). The 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).

Compatibility

[edit]
  • 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 (is32, il32, ih32, 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

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

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.

'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).

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 icns header.

Non-PNG / JPEG2000 Element Types

[edit]

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

[edit]
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.[6] 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).

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

[edit]

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

[edit]

Various apps can open *.icns files including Preview and GTK+, with some offering the ability to convert *.icns to and from PNG as well.[7][8][9] 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.[10]

See also

[edit]

References

[edit]
[edit]
Revisions and contributorsEdit on WikipediaRead on Wikipedia

Apple Icon Image format

View on Grokipedia
from Grokipedia
The Apple Icon Image format (ICNS) is a container file format developed by Apple Inc. for storing icons in the macOS operating system, enabling multiple image representations of varying sizes and color depths to be bundled into a single file for efficient rendering across user interfaces. It serves as the native icon resource for macOS applications, documents, folders, and system elements, analogous to the ICO format on Windows but optimized for Apple's ecosystem. Introduced with Mac OS X in 2001 as a successor to the resource fork-based icons of , the ICNS format has evolved to accommodate higher resolutions, including support for high-resolution displays introduced in macOS in 2012. The file structure begins with an 8-byte header identifying it as "icns," followed by a series of data sections—each prefixed with a four-character code (e.g., "il32" for 32×32 32-bit color icons or "ic08" for 256×256 pixels)—containing embedded images typically encoded in or formats. It supports square icon sizes from 16×16 pixels up to 1024×1024 pixels (or 512×512 for some legacy contexts), with additional @2x variants for high-density displays, and color depths ranging from monochrome (1-bit) to full color with 8-bit alpha transparency (32-bit total). In macOS development, ICNS files are created using tools like Icon Composer in , where designers import layered artwork in or and generate the bundled icon for integration into app bundles via the Info.plist file's CFBundleIconFile key. This format ensures icons scale appropriately without loss of quality in contexts like the , Finder, or Launchpad, while also supporting compression to reduce file size without compromising visual fidelity. Although proprietary, ICNS remains integral to macOS iconography, with cross-platform tools available for viewing and editing on non-Apple systems.

Overview

History and Development

The 'icns' resource type for the Apple Icon Image format (ICNS) was introduced with Mac OS 8.5 in October 1998 as a successor to earlier resource-based icon formats like 'ICON' and 'ICN#', consolidating multiple icon elements into a single resource type and initially supporting resolutions up to 32×32 pixels for color and monochrome icons. This shift addressed limitations in the fragmented legacy system, enabling more efficient storage and rendering of icons within application resources. The standalone ICNS file format was then introduced with Mac OS X in March 2001. With the launch of Mac OS X in March 2001, the ICNS format expanded significantly to support larger 128×128 pixel icons and color depths up to 24-bit RGB, aligning with the demands of the new Aqua user interface for higher-fidelity visuals in the Finder and applications. In October 2003, Apple introduced the Icon Composer tool as part of the Developer Tools in Mac OS X 10.3 Panther, providing developers with a dedicated application for assembling and editing multi-resolution ICNS files. The format continued to evolve with hardware advancements; in July 2011, Mac OS X 10.7 Lion added support for displays, including high-resolution variants such as 32×32@2x icons to maintain sharpness on double-density screens. In 2018, macOS 10.14 Mojave introduced nested structures within ICNS files for dark mode variants, allowing icons to adapt dynamically to system appearance settings. Further extensions arrived in November 2020 with macOS 11 , incorporating ARGB formats (e.g., ic04 for 16×16 and ic05 for 32×32) for enhanced alpha channel handling. Since macOS 11, Apple has shifted emphasis toward asset catalogs in for managing app icons, reducing reliance on standalone ICNS files but ensuring ongoing backward compatibility for existing resources. In June 2025, Apple introduced a new Icon Composer tool at WWDC 2025 for creating layered Liquid Glass app icons. This evolution in the ICNS file structure has paralleled changes in data block OSTypes, enabling more flexible organization of icon elements over time.

Purpose and Usage

The Apple Icon Image format (ICNS) serves as a file that bundles multiple representations of an at various resolutions, ranging from 16×16 pixels to 1024×1024 pixels, including high-density variants such as @2x for displays, allowing macOS to select the appropriate size for different contexts without quality degradation. This multi-resolution structure supports lossless storage of images in formats from 1-bit monochrome to 32-bit color depths, incorporating alpha channels for transparency, which enables crisp, scalable-like rendering across elements without artifacts. In macOS, ICNS files are primarily employed for application icons, document type icons, Finder thumbnails, and custom cursors, providing a unified way to associate visual identifiers with software bundles, file types, and interactions. The format's file extension is .icns, with the MIME type , facilitating its recognition and handling by the operating and development tools. For instance, in a macOS application bundle, the ICNS file is conventionally placed at Contents/Resources/app.icns to define the app's primary icon, which the automatically extracts and displays in the , Launchpad, and other interfaces. As of November 2025, ICNS remains integral for legacy applications and custom icon implementations in macOS, though modern Xcode workflows favor .appiconset asset catalogs containing individual PNG files, which are automatically compiled into ICNS during the build process using tools like iconutil for efficiency and source control compatibility. This approach evolved from the resource fork-based icon storage in pre-OS X Macintosh systems, adapting to contemporary bundle structures while preserving backward compatibility.

File Format Structure

The Apple Icon Image format (ICNS) file begins with a fixed 8-byte header that identifies the file type and provides its total size, acting as the primary entry point for parsers to validate and process the container. This header consists of two main components: the first four bytes (positions 0-3) store the magic number as the ASCII string "icns", equivalent to the hexadecimal sequence 69 63 6E 73, which unambiguously confirms the file as an ICNS resource. The subsequent four bytes (positions 4-7) encode the total file length as a big-endian unsigned 32-bit integer, representing the entire size of the file in bytes, including the header; this length must be at least 8 to indicate a minimally valid structure. Parsers typically validate the header by first checking the magic number for correct identification and then comparing the reported length against the actual to ensure integrity and prevent processing truncated or malformed files. The ICNS header lacks a dedicated version field, with any version details instead conveyed through an optional 'icnV' data block elsewhere in the file. Following the header, the file proceeds directly into variable-length data blocks that comprise the elements.

Data Blocks

The core content of an ICNS file follows its 8-byte header and consists of one or more variable-length data blocks, each representing an icon element such as an image or metadata component. These blocks form the repeating structure that allows the format to support multiple resolutions and types within a single file. Each data block begins with a 4-byte OSType identifier, a four-character code that specifies the block's content type—for example, 'il32' denotes a 32×32 pixel RGB icon without compression. Immediately following is a 4-byte big-endian unsigned integer representing the total length of the block, including the OSType and length fields themselves. The remaining variable data portion then follows, with its effective size calculated as the reported length minus 8 bytes to account for the fixed header overhead. This self-describing structure enables efficient parsing without requiring external metadata. Data blocks may appear in any order after the file header, providing flexibility in how icon families are assembled. Duplicates of the same OSType are permitted, though practical implementations typically include only one block per type to avoid redundancy. The overall file size is predetermined by the 4-byte length field in the header (preceded by the 'icns' magic number), ensuring that parsing terminates at the exact end of the content. To parse an ICNS file, the header is read first to verify the format and total length, after which blocks are processed sequentially by extracting the OSType, length, and data until the file end is reached. Blocks are optional based on the icon's needs; for instance, a minimal ICNS file might contain just one data block for a single-resolution icon, while more complex files include multiple blocks for various sizes and formats. This supports and extensibility in macOS icon handling.

Table of Contents

The Table of Contents block in the Apple Icon Image format (ICNS) is an optional data block that provides an index of all subsequent icon data blocks within the file. Identified by the OSType 'TOC ' (hexadecimal: 54 4F 43 20), this block enables efficient parsing by allowing applications to quickly identify available icon types without sequentially scanning the entire file structure. It also facilitates validation of the file's completeness by listing expected block types, which can help detect corruption or incomplete generations. The structure of the TOC block follows the standard ICNS data block template, beginning with the 4-byte OSType followed by a 4-byte length field indicating the total size of the block, including the header. The data portion starts with a 4-byte big-endian representing the block count NN, the number of subsequent icon data blocks in the file. This is followed by NN pairs, each consisting of a 4-byte OSType and a 4-byte length corresponding to one of the icon elements listed in sequence after the TOC block itself. The total length of the TOC block is thus 12+8N12 + 8N bytes. This block is commonly included in ICNS files generated by Apple's iconutil command-line tool, which converts icon sets to the ICNS format and automatically adds the TOC for better compatibility with modern macOS versions. It is typically absent in simpler or manually constructed files, particularly those predating macOS 10.7 (Lion), where the TOC was introduced. For instance, an ICNS file containing a 32-bit RGB ('il32') and an 8-bit mask ('t8mk') would have a TOC block with N=2N = 2, followed by the OSTypes 'il32' and 't8mk' along with their respective lengths in that order.

Icon Element Types

Legacy Monochrome and Indexed Types

The legacy monochrome and indexed types in the Apple Icon Image format (ICNS) represent the original low-color icon elements developed for early Macintosh systems, primarily supporting black-and-white displays and limited color depths before the introduction of full RGB capabilities. These types were stored as resources in classic Mac OS applications and files, using specific OSTypes to identify their structure and purpose. They enabled simple icon rendering on hardware with constrained graphics capabilities, such as the original Macintosh 128K's 1-bit monochrome screen. Monochrome types operate at 1-bit depth, representing pixels as either on () or off (), and were the foundational format for from System 1.0 onward. The primary types include '', a basic 32×32 1-bit without a ; 'ICN#', a 32×32 1-bit accompanied by a separate 1-bit for transparency handling; 'ics#', a 16×16 1-bit with for small ; 'icm#', a 16×12 1-bit with suited for items; and 'ich#', a larger 48×48 1-bit with for high-resolution displays. Data for these types consists of packed bits, with each bit corresponding to one , arranged left-to-right and top-to-bottom in rows padded to 32-bit boundaries (4 bytes per row for 32- widths). The , where present, is stored immediately after the icon data as an equivalent bit-packed , defining opaque regions by setting bits to 1. This format totals 256 bytes for a standard 32×32 'ICN#' resource (128 bytes for the icon and 128 for the ). No explicit palette is used, as pixels map directly to (1) or (0), with selection states handled by system inversion or gray scaling on color displays. Indexed types extend monochrome support to limited color via 4-bit (16 colors) and 8-bit (256 colors) depths, introduced with color-capable Macintosh models like the in 1987. For 4-bit, the OSTypes are 'icm4' (16×12), 'ics4' (16×16), and 'icl4' (32×32); for 8-bit, they are 'icm8' (16×12), 'ics8' (16×16), 'icl8' (32×32), and 'ich8' (48×48). These store pixel indices in packed format: 4 bits per pixel for the former (2 pixels per byte) and 1 byte per pixel for the latter, again row-aligned to byte boundaries. Masks can accompany these as separate 1-bit bitmaps, similar to monochrome types. Palettes for these indexed formats rely on fixed system color tables; 4-bit icons typically use a basic palette of black, white, and intermediate grays for shading, while 8-bit icons draw from the Mac OS standard 256-color system palette, which includes 34 designated colors optimized for icons (such as subtle ramps for blending and highlights, plus bright accents like the Apple logo red). This ensures consistent rendering across displays, with the system remapping indices if the device palette differs. These legacy types may incorporate basic compression in some implementations to reduce resource size, though uncompressed packed data is standard. Although rarely utilized in modern macOS applications following the shift to ICNS containers with Mac OS X (2001), they remain supported for , allowing software to run under emulation or Rosetta without icon rendering issues. Developers must include them in hybrid bundles for full legacy app support on contemporary systems.

RGB and High-Resolution Types

The RGB and high-resolution types in the Apple Icon Image format provide support for full-color icons, transitioning from earlier low-depth formats to enable detailed, vibrant visuals suitable for contemporary user interfaces and high-DPI displays. These types encompass 24-bit RGB representations for legacy compatibility and 32-bit ARGB for transparency, alongside scalable high-resolution variants that leverage compressed image data to optimize and rendering performance. Legacy RGB types store 24-bit color data in raw RGB channels, typically compressed using a PackBits-like algorithm per channel, and are designed for standard resolutions without embedded formats. The primary types include:
OSTypeResolutionDescription
is3216×16 pixels24-bit RGB icon data
il3232×32 pixels24-bit RGB icon data
ih3248×48 pixels24-bit RGB icon data
it32128×128 pixels24-bit RGB icon data
ARGB types extend this with integrated alpha channels in a 32-bit format, also using for smaller sizes. Key examples are 'ic04' for 16×16 pixels and 'ic05' for 32×32 pixels. High-resolution types mark a significant advancement, incorporating embedded or data for efficient storage of larger, lossless images, particularly for and beyond displays. While is supported, is recommended and preferred since macOS 10.13 High Sierra. Representative OSTypes include 'ic08' for 256×256 pixels, 'ic09' for 512×512 pixels, 'ic10' for 1024×1024 pixels (or 512×512@2x), 'icp5' for 32×32 pixels, 'icp6' for 64×64 pixels, and 'ic07' for 128×128 pixels, all supporting or encoding. Retina-specific variants scale logical sizes at 2x density, such as 'ic11' for 16×16@2x (32×32 pixels), 'ic12' for 32×32@2x (64×64 pixels), 'ic13' for 128×128@2x (256×256 pixels), and 'ic14' for 256×256@2x (512×512 pixels). These types evolved to address the demands of high-DPI screens, with / integration and initial support introduced in macOS 10.7 Lion (corresponding to era developments for similar icon scaling), while larger 1024×1024 sizes like 'ic10' became standard for submissions around macOS 10.8 and gained broader system integration in macOS 10.15 Catalina and later. Legacy RGB and ARGB types often pair with dedicated mask elements, such as 't8mk' for 128×128 alpha handling.

Auxiliary and Nested Types

The auxiliary types in the Apple Icon Image format (ICNS) include elements and metadata blocks that support transparency and provide contextual details without representing primary data. These are essential for enhancing icon rendering and compatibility across macOS applications. types store grayscale data as an alpha channel, allowing precise control over transparent regions when combined with corresponding RGB icon elements. Metadata types offer supplementary information such as version details or labels, stored in simple binary formats. Mask types are defined by specific OSTypes and correspond to common resolutions, with each pixel's alpha value represented by an 8-bit byte (0 for fully transparent, 255 for fully opaque). The data is uncompressed and arranged row by row. The following table summarizes the primary mask types:
OSTypeResolution (bytes)Description
's8mk'16×162568-bit alpha for small icons, providing transparency for or low-resolution variants.
'l8mk'32×321,0248-bit alpha for standard icons, enabling shaped or irregular boundaries.
'h8mk'48×482,3048-bit alpha for high-density displays, supporting detailed transparency in icons.
't8mk'128×12816,3848-bit alpha for large icons, used in file previews or high-resolution contexts.
These masks pair with RGB types to create composite icons, where the system applies the alpha values during rendering for effects like feathered edges or cutouts. Metadata types store non-visual attributes via dedicated OSTypes. The 'icnV' type contains a 4-byte big-endian integer representing the version of Apple's Icon Composer tool used to generate the ICNS file, aiding in format compatibility checks. The 'name' type holds a Pascal-style string (length byte followed by UTF-8 characters) serving as a , such as "icon" or a descriptive identifier for the resource. The 'info' type is a binary (plist) encoding icon properties, including potential attributes like role or customization flags, though its full structure remains implementation-specific. Nested types enable embedding of sub-ICNS structures or variants within the main file, facilitating multi-state or themed icons without separate files. The 'sbtp' OSType embeds a template ICNS (nested "template" icns file; usage unknown). The 'slct' OSType contains a selected-state ICNS (nested "selected" icns file; usage unknown). These nested blocks omit the standard ICNS header and reference the for integration. The 'sb24' and 'SB24' OSTypes support 24×24 pixel variants (and 48×48 for SB24), often for notification badges or compact UI elements, storing compressed data compatible with system rendering. For adaptive theming, the ICNS format includes a nested dark mode variant identified by the OSType bytes 0xFD 0xD9 0x2F 0xA8 (introduced in macOS 11), embedding a full ICNS tailored for dark system appearances to ensure seamless icon switching based on user preferences. This allows developers to provide light and dark variants in a single file, enhancing consistency in modern macOS interfaces.

Image Data Formats

Color Depth and Palettes

The Apple Icon Image format (ICNS) supports multiple s to enable compatibility with legacy and modern macOS displays, ranging from simple representations to full-color images with millions of hues. The 1-bit depth provides icons limited to black, white, and transparent s, ideal for early systems lacking color support. This depth uses a single bit per to define these states, prioritizing minimal and fast rendering. Indexed color modes offer more variety through predefined palettes. The 4-bit depth employs a fixed palette of 16 colors, commonly including shades or basic hues like , , and for straightforward icon artwork that degrades gracefully on limited hardware. The 8-bit depth expands to 256 colors using the system palette, a standard set designed for consistent icon rendering across applications; in this palette, index 0 denotes black and index 255 denotes white, with intermediate indices filling out subdued tones and ramps for shading. For true color, the 24-bit RGB depth allocates 8 bits per channel to , , and components, supporting over 16 million distinct colors suitable for detailed icons. Data in this format may be stored as three separate channels or embedded within compressed structures like or , particularly for higher-resolution elements to optimize storage without loss of quality. The 32-bit ARGB depth extends RGB by adding an 8-bit alpha channel, enabling per-pixel opacity; it structures data across four channels (alpha, , , ). Compression may be applied to these channels in certain implementations to reduce file sizes. ICNS exclusively relies on RGB-based models and excludes support for CMYK or other non-RGB color spaces, aligning with its focus on screen-display icons rather than print media.

Alpha and Mask Handling

In the legacy monochrome icons of the ICNS format, transparency is handled through separate 1-bit blocks, such as those associated with the 'ICN#' OSType for 32×32 pixels, where the serves as a distinguishing opaque from transparent pixels. These are typically shared across elements of the same size, encoding simple binary opacity (fully opaque or fully transparent) without variations. For modern implementations, transparency support expands to 8-bit alpha using OSTypes like 's8mk' for 16×16 , 'l8mk' for 32×32, and similar variants up to 't8mk' for 128×128, represented as where values range from 0 (fully transparent) to 255 (fully opaque). These separate blocks pair with color in formats like 'is32' (16×16 32-bit RGB), ensuring the dimensions exactly match the corresponding size to avoid rendering artifacts. If a block is absent for a given element, the system defaults to treating the entire as fully opaque. In RGB-based icon types, alpha is often integrated directly using pre-multiplied alpha channels in ARGB , where the , green, and blue color components are scaled by the alpha value prior to storage, facilitating efficient during rendering. This approach applies to 32-bit icons across various resolutions, maintaining compatibility with macOS graphics pipelines that expect pre-multiplied values. For compressed formats like and embedded within ICNS (e.g., via OSTypes 'icp4' or 'jp2k'), transparency leverages the native alpha channel support of these standards, but full 32-bit depth (RGBA) is required for proper compatibility and to preserve per-pixel opacity without loss. elements, in particular, store straight alpha that may be converted to pre-multiplied during ICNS processing, while supports both regular and pre-multiplied alpha layers for high-resolution icons.

Compression Algorithms

The Apple Icon Image format (ICNS) utilizes distinct compression methods for its image data blocks, tailored to legacy and modern icon types, with no overarching compression applied to the entire file structure. Each block's data is either raw, run-length encoded, or embedded in a standard format, ensuring efficient storage while maintaining compatibility across macOS versions. For legacy RGB icon elements, such as those identified by 'il32' or 'is32' OSTypes, the format applies a per-channel run-length encoding (RLE) scheme akin to PackBits, processing the red, green, and blue channels independently to exploit spatial redundancies in icon imagery. This lossless method reduces file size by encoding sequences of identical bytes efficiently, with each channel's data decompressed separately before recombination into a full RGB image. The RLE encoding operates on byte streams using an unsigned 8-bit control value n (0–255): values of n from 0 to 127 specify n + 1 literal bytes to copy directly from the input, allowing up to 128 consecutive unique bytes per segment; values from 128 to 255 specify n – 125 repetitions of the subsequent single byte, supporting runs from 3 to 130 identical bytes. Decompression proceeds iteratively until the target buffer reaches the expected size, typically the channel's count (e.g., bytes for a 32×32 ). for the process is as follows:

function decompress_rle(input, target_size): output = empty buffer while length(output) < target_size: n = read_byte(input) if n <= 127: for i = 1 to (n + 1): append read_byte(input) to output else: b = read_byte(input) repeat_count = n - 125 for i = 1 to repeat_count: append b to output return output

function decompress_rle(input, target_size): output = empty buffer while length(output) < target_size: n = read_byte(input) if n <= 127: for i = 1 to (n + 1): append read_byte(input) to output else: b = read_byte(input) repeat_count = n - 125 for i = 1 to repeat_count: append b to output return output

This routine is executed once per channel, yielding uncompressed byte arrays for R, G, and B. In ARGB legacy elements, like 'argb' or 'arga', the scheme extends to four channels (alpha, red, green, blue), each undergoing identical RLE compression to handle transparency alongside color data. Modern ICNS elements, particularly for high-resolution icons (e.g., 256×256 or 512×512 pixels, including retina variants), preferentially embed data for lossless compression, leveraging DEFLATE-based algorithms inherent to the PNG standard without additional ICNS-level encoding. is alternatively employed for lossy compression in larger variants, enabling smaller file sizes at the cost of minor quality loss, suitable for non-critical icon details. These embedded formats are stored directly within their respective blocks, preserving their internal compression while integrating seamlessly into the ICNS container.

Compatibility and Implementation

Platform and Version Support

The 'icns' resource type was introduced in Mac OS 8.5 as a unified resource to encapsulate various icon representations, replacing earlier fragmented formats like 'ICON', 'ICS#', and 'ICN#'. The (ICNS) file (.icns) has native full support in macOS starting from version 10.0 (2001). Prior to macOS 10.7 (Lion), legacy monochrome and indexed color types within ICNS files were required for compatibility with older displays and applications, as these ensured proper rendering on systems without full 32-bit color support. From macOS 10.5 (Leopard), ICNS began supporting embedded PNG data for higher-quality icons, enabling lossless compression and alpha channel handling without relying solely on older raster formats. Enhanced features, including 1024×1024 pixel resolutions, were added in macOS 10.7 (Lion, released in 2011), allowing for sharper icons on ; ARGB color space was supported earlier. Nested dark mode variants were added in macOS 10.14 (Mojave, 2018). On iOS and iPadOS, ICNS files are not directly used for app icons; instead, icons are compiled from individual PNG files during the build process via asset catalogs, though partial rendering of ICNS is possible in iOS simulators for development testing. Cross-platform compatibility is limited but achievable through third-party libraries: on Windows, libicns provides reading and writing capabilities for ICNS manipulation in applications; on Linux, GTK+ environments can display ICNS icons via integration with libicns for extraction and rendering as PNG. As of November 2025, ICNS remains required for custom app icons in macOS application bundles to ensure system-wide consistency. Apple recommends using SF Symbols for vector-based icons and asset catalogs for raster images, which generate ICNS internally, promoting scalable, theme-adaptive designs.

Tooling and Conversion Utilities

Apple provides several native tools for creating and managing ICNS files. The command-line utility iconutil, included with macOS, converts a directory of PNG images in an .iconset folder to a single ICNS file or vice versa, supporting high-resolution formats up to 1024x1024 pixels. Icon Composer, a graphical application integrated into recent versions of Xcode (accessible via Xcode > Open Developer Tool > Icon Composer), allows users to design layered icons with adjustable properties like depth and lighting effects, exporting directly to ICNS for use across macOS, iOS, iPadOS, and watchOS platforms. As of WWDC 2025, Icon Composer supports advanced features like "Liquid Glass" effects for theme-adaptive icons. Third-party image editing software supports ICNS workflows through export and conversion steps. lacks native ICNS export but enables creation by preparing multi-resolution PNGs, which can then be processed with iconutil to generate ICNS files containing multiple resolutions. requires a third-party plugin, such as gimp-icns, to read and write ICNS files directly, facilitating icon design and export for macOS developers. Online services like CloudConvert offer straightforward PNG-to-ICNS conversion without software installation, handling batch uploads and supporting common resolutions while preserving transparency. Programming libraries provide programmatic access to ICNS manipulation across languages. The C library libicns enables reading, writing, and extracting elements from ICNS files, including support for embedding and images within the format. In Python, the icnsutil package offers comprehensive functions for converting, extracting, and composing ICNS files, with built-in handling for and data types. developers can use the to encode and decode ICNS structures, supporting common icon types like 32-bit ARGB and compression. For Go, the go-icns library (also known as icns package) facilitates generating ICNS from inputs, with utilities for high-resolution icon sets. Conversion from sets of PNG images to ICNS is streamlined by tools that automate multi-resolution assembly; for example, naming files like icon_16x16.png, icon_32x32.png, up to icon_1024x1024.png in an .iconset folder allows iconutil to bundle them into a single ICNS with elements like ic04 for 256x256 RGBA. is available via applications like Image2icon, a macOS utility that resizes a single source image to all required sizes and outputs an optimized ICNS file. Best practices for modern ICNS creation emphasize providing 1x and 2x resolution PNGs (e.g., 512x512 for 1x and 1024x1024 for 2x) to ensure crisp rendering on displays, as recommended by Apple for app icons. Validation can be performed using the macOS sips command-line tool to inspect or convert the ICNS and confirm structural integrity across resolutions. macOS includes built-in support for ICNS via Icon Services, allowing seamless integration in development workflows.

Known Limitations

One notable limitation in the ICNS format involves transparency handling, where combining certain types like 'il32' (32-bit ARGB for large icons) with 'icl8' (8-bit mask) can lead to artifacts or ignored masks during rendering, resulting in opaque icons instead of transparent ones. Additionally, decoding issues with ARGB may cause the blue channel to drop the last byte, leading to color inaccuracies in rendered icons. In some frameworks like , embedding compressed formats such as or within ICNS files for application icons may fail to render correctly on macOS 10.15 and later versions, producing blank or distorted icons; developers are advised to use raw ARGB instead to ensure proper display. The ICNS format has no official maximum size beyond 1024×1024 pixels, though most tools and system implementations cap support at this resolution for reasons, and it lacks native vector support, requiring raster images that do not scale indefinitely without quality loss. Compatibility gaps exist with high-resolution displays, where legacy monochrome or low-resolution types (e.g., 'ICN#') are ignored in favor of Retina-optimized variants like 'il32', potentially causing if higher-resolution elements are absent. Similarly, nested dark mode icons within ICNS files are not parsed or rendered before macOS 10.14 (Mojave, 2018), falling back to light mode variants on earlier systems. As of November 2025, while the ICNS format continues to be used, it offers no native support for efficient contemporary codecs like or , which provide superior compression for high-resolution assets; Apple prefers asset catalogs with individual files to enable better integration with tools like . Common workarounds include providing separate icons (e.g., 'icl8' or 'ic08') alongside primary images to enforce transparency without relying on combined types, and validating the (TOC) structure during file creation to ensure all required elements are present and correctly indexed, preventing parsing errors.

References

  1. https://www.cleverfiles.com/howto/recover-deleted-icns.html
  2. https://file-extensions.com/docs/icns
  3. http://justsolve.archiveteam.org/wiki/ICNS
  4. https://www.apple.com/newsroom/2012/06/11Apple-Introduces-New-MacBook-Pro-with-Retina-Display/
  5. https://docs.fileformat.com/image/icns/
  6. https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer
  7. https://arstechnica.com/gadgets/2000/02/mac-os-x-dp3/
  8. https://preserve.mactech.com/articles/mactech/Vol.15/15.05/IconServicesInApps/index.html
  9. https://files.iconfactory.net/archive/if4/howto_home.htm
  10. http://interface.free.fr/Archives/AquaHIGuidelines.pdf
  11. https://eclecticlight.co/2023/03/04/custom-finder-icons-resources-and-mac-os-history/
  12. https://osxdaily.com/2011/04/24/high-resolution-icons-in-mac-os-x-lion-further-hint-at-mac-retina-displays/
  13. https://developer.apple.com/videos/play/wwdc2025/361/
  14. https://developer.apple.com/library/archive/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Optimizing/Optimizing.html
  15. https://greenfishsoftware.org/help/gfie/English/mac_icon.html
  16. https://pcpartguide.com/icns-viewer/
  17. https://mimetype.io/image/x-icns
  18. https://stackoverflow.com/questions/12306223/how-to-manually-create-icns-files-using-iconutil
  19. https://www.nationalarchives.gov.uk/PRONOM/Format/Detail.aspx?id=1995
  20. https://www.garykessler.net/library/file_sigs.html
  21. https://lucasklassmann.com/blog/2018-07-21-handling-binary-files-in-go/
  22. https://docs.rs/icns/latest/icns/
  23. https://github.com/mdsteele/rust-icns
  24. http://icns.sourceforge.net/apidocs.html
  25. https://developer.apple.com/library/archive/documentation/mac/pdf/MoreMacintoshToolbox.pdf
  26. http://preserve.mactech.com/articles/mactech/Vol.05/05.10/ColorIcons/index.html
  27. https://dev.os9.ca/techpubs/mac/HIGuidelines/HIGuidelines-172.html
  28. https://docs.rs/icns
  29. https://github.com/fiahfy/icns
  30. https://developer.apple.com/documentation/technologies
  31. https://discussions.apple.com/thread/4131917
  32. https://docs.rs/icns/latest/icns/enum.IconType.html
  33. https://docs.rs/icns/latest/icns/enum.IconType.html#variant.Mask8_16x16
  34. https://docs.rs/icns/latest/icns/enum.IconType.html#variant.Mask8_32x32
  35. https://docs.rs/icns/latest/icns/enum.IconType.html#variant.Mask8_48x48
  36. https://docs.rs/icns/latest/icns/enum.IconType.html#variant.Mask8_128x128
  37. https://apple.stackexchange.com/questions/471872/to-edit-trashicon-icns-using-hex-editor-to-get-access-to-the-dark-icons
  38. https://icns.sourceforge.io/apidocs.html
  39. https://blog.persistent.info/1998/10/rle-decyphered.html
  40. http://preserve.mactech.com/articles/mactech/Vol.15/15.05/IconServicesInApps/index.html
  41. https://whitefiles.org/mac/pgs/t02.htm
  42. https://github.com/dgelessus/python-icns
  43. https://stackoverflow.com/questions/12772346/retina-ready-icns-icon-file-on-10-5-leopard-size-limit
  44. https://www.axialis.com/tutorials/macintosh-vs-windows-icons.html
  45. https://developer.apple.com/design/human-interface-guidelines/app-icons
  46. https://icns.sourceforge.io/
  47. https://github.com/kornelski/libicns
  48. https://developer.apple.com/design/human-interface-guidelines/sf-symbols
  49. https://developer.apple.com/icon-composer/
  50. https://github.com/bvibber/gimp-icns
  51. https://cloudconvert.com/png-to-icns
  52. https://pypi.org/project/icnsutil/
  53. https://crates.io/crates/icns
  54. https://pkg.go.dev/github.com/jackmordaunt/icns
  55. https://img2icnsapp.com/
  56. https://discussions.apple.com/thread/252809419
  57. https://github.com/electron/electron-packager/issues/756
  58. https://developer.apple.com/design/human-interface-guidelines/icons
  59. https://discussions.apple.com/thread/2533334
  60. https://github.com/Ji4n1ng/OpenInTerminal/issues/211
  61. https://developer.apple.com/documentation/xcode/configuring-your-app-icon
  62. https://stackoverflow.com/questions/44506713/using-sips-to-create-an-icns-file-from-a-png-file
Add your contribution
Related Hubs
User Avatar
No comments yet.