The Apple Icon Image format is an
icon
An icon () is a religious work of art, most commonly a painting, in the cultures of the Eastern Orthodox, Oriental Orthodox, and Catholic churches. They are not simply artworks; "an icon is a sacred image used in religious devotion". The most ...
format used in
Apple Inc.
Apple Inc. is an American multinational technology company headquartered in Cupertino, California, United States. Apple is the largest technology company by revenue (totaling in 2021) and, as of June 2022, is the world's biggest company b ...
's
macOS
macOS (; previously OS X and originally Mac OS X) is a Unix operating system developed and marketed by Apple Inc. since 2001. It is the primary operating system for Apple's Mac computers. Within the market of desktop and lapt ...
. 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
In computer architecture, 8-bit Integer (computer science), integers or other Data (computing), data units are those that are 8 bits wide (1 octet (computing), octet). Also, 8-bit central processing unit (CPU) and arithmetic logic unit (ALU) arc ...
alpha channel
In computer graphics, alpha compositing or alpha blending is the process of combining one image with a background to create the appearance of partial or full transparency. It is often useful to render picture elements (pixels) in separate pas ...
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
macOS Big Sur (version 11) is the seventeenth major release of macOS, Apple Inc.'s operating system for Macintosh computers. It was announced at Apple's Worldwide Developers Conference (WWDC) on June 22, 2020, and was released to the public ...
, 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
* The value inside the parenthesis is the uncompressed length for ARGB and 24-bit RGB icons.
* 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 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 may refer to:
Physical science
*Compression (physics), size reduction due to forces
*Compression member, a structural element such as a column
*Compressibility, susceptibility to compression
* Gas compression
*Compression ratio, of a ...
). The 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 may refer to:
Physical science
*Compression (physics), size reduction due to forces
*Compression member, a structural element such as a column
*Compressibility, susceptibility to compression
* Gas compression
*Compression ratio, of a ...
).
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 (, , , ) 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
* 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.
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 (, , , , , ) and ARGB (, , ) pixel data are compressed (per channel) with a format similar to
PackBits
PackBits is a fast, simple lossless compression scheme for run-length encoding of data.
Apple introduced the PackBits format with the release of MacPaint on the Macintosh computer. This compression scheme can be used in TIFF files. TGA files also ...
.
[Macintosh Icons](_blank)
/ref>
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).
The following pseudocode
In computer science, pseudocode is a plain language description of the steps in an algorithm or another system. Pseudocode often uses structural conventions of a normal programming language, but is intended for human reading rather than machine re ...
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: should decompress to
Known issues
As of macOS 11, there are certain issues / bugs with the file format:
# Setting or will display a proper icon. But setting 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 may refer to:
Physical science
*Compression (physics), size reduction due to forces
*Compression member, a structural element such as a column
*Compressibility, susceptibility to compression
* Gas compression
*Compression ratio, of a ...
). 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:
#*
#*
# macOS 10.15.7 (likely earlier) and later versions have an issue displaying PNG and JPEG 2000 icons for the keys (16x16), (32x32), and (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 and (macOS 11+) or the old 24-bit RGB + alpha mask format. Use the latter with the old keys and , or with the newer keys and (writing RGB data into PNG fields). 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 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. GTK+
GTK (formerly GIMP ToolKit and GTK+) is a free and open-source cross-platform widget toolkit for creating graphical user interfaces (GUIs). It is licensed under the terms of the GNU Lesser General Public License, allowing both free and proprie ...
can load *.icns resources since 2007. Other tools supporting the format include the Apple Icon Composer and icns Browser, The Iconfactory
The Iconfactory is a software and graphic design company that designs commercial icons and User interface design, user interfaces and publishes desktop applications and mobile apps for macOS and iOS.
History
The Iconfactory was founded in April ...
, and IconBuilder
IconBuilder is a popularLarry Ullman, Marc Liyanage, ''Mac OS X Panther timesaving techniques for dummies'', For Dummies, 2004, , p127/ref> plugin for Adobe Photoshop, Adobe Photoshop Elements and Macromedia Fireworks for the editing and creati ...
.
MacOS offers the built-in iconutil
command line tool to pack and unpack *.icns files.
See also
* ICO format on Windows
Windows is a group of several proprietary graphical operating system families developed and marketed by Microsoft. Each family caters to a certain sector of the computing industry. For example, Windows NT for consumers, Windows Server for serv ...
* X PixMap
X PixMap (XPM) is an image file format used by the X Window System, created in 1989 by Daniel Dardailler and Colas Nahaboo working at Bull Research Center at Sophia Antipolis, France, and later enhanced by Arnaud Le Hors.
It is intended primaril ...
format for X11
The X Window System (X11, or simply X) is a windowing system for bitmap displays, common on Unix-like operating systems.
X provides the basic framework for a GUI environment: drawing and moving windows on the display device and interacting wi ...
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
{{Graphics file formats
Graphics file formats
MacOS
Computer icons