Macintosh Icons

Summary: Information page on Macintosh icons. What are they? How are they built? Is it possible to produce them on a PC?


This page is a rather technical one, on Macintosh icon resources. Since I had a pretty hard time finding out several of those pieces of information, I decided to publish it on the Web site.

Technical Aspects of Custom Icons

Technically, the matter is not very complicated. Custom icons are normal icon resources, but must bear the "magical" -16455 identification number. More, the "custom icon" flag of the folder record must be set.
In the case of files, the same graphic resources must be stored in the resource fork of the file. This time, the flag is set in the file record.
Those icon resources are not stored by the Finder in its database (Desktop).

Folder Custom Icons

The folder (the root folder for the volume) must contain a hidden file named "icon " (0x0D as the last character) holding correct graphic resources (see the page on Macintosh Icons in WinComposer help for more technical information).

Volume Custom Icons

Under Mac OS 9 and below, the root folder is treated like a normal folder, and should contain the same 'icon ' file.
Under Mac OS X, the file holding the icon must be named '.VolumeIcon.icns' and the icon format must be an 'icns' resource. This resource is stored in the data fork.
If you target all versions of the Macintosh operating system, you may include both files. Older versions won't do anything with the '.VolumeIcon.icns' file. Under Mac OS X, all files beginning with a dot are (like under Unix) treated as system and hidden files. This is not the case under Mac OS 9 and below. You should therefore hide those files (set the hidden flag) to avoid perplexity amongst users.


Visitors interested by a more basic presentation of Macintosh (custom) icons should visit our page on WinComposer, a Windows utility to compose Macintosh icons.
See also our page on Macintosh Custom Icons, how to produce them with WinComposer and how to integrate them in the CD-ROMs built by MacImage.

Different Resource Types Used for Icons


The Modern icns Resource

Most of above icon resources have a rather historical nature. The current trend is to use exclusively the icns resource. This resource is a container, with several individual icon resources contained within it. The system accesses therefore in a single stroke all necessary icon resources.
This resource kind, which is not known by the old and trusty ResEdit utility (which only displays the hex contents), was introduced with Mac OS 8.5.
For safety reasons, one should always include in the resource file an older ICN# resource, which can be drawn by all versions of the system, even if the probability of being used on an older system is now rather low.
In the same vein, it is probably overkill to include in such a resource the older 4bpp icon resources (16 color palette).
A modern icns resource should therefore contain the ICN# resource and the 32 bpp icons, in 32*32 pixels, 48*48 pixels and maybe 128*128 pixels.

Compression Scheme

The data of 32 bits/pixel icons may be compressed. One should check whether the data length corresponds to the theoretical length (width * height). If not, the data is compressed, channel by channel. The alpha channel is not stored in the data set. It should be recovered from the corresponding ?8mk resource (see the table above).
In some icon sizes, there is a 32bit integer at the beginning of the run, whose role remains unknown.


The compression method is not documented by Apple. It was reverse-engineered, probably by Peter Stuer. I used as a basis the code of ResCafé, an exploration utility for Macintosh resources, written in Java by G. Brannon Smith.

For each of the color channels (red, green, blue),
and for the maximum length (width * height of the icon), read a byte.
if bit 8 of the byte is set:
   This is a compressed run, for some value (next byte).
   The length is byte - 125.
   Put so many copies of the byte in the current color channel.
   This is an uncompressed run, whose values follow.
   The length is byte +1.
   Read the bytes and put them in the current color channel.

Pierre Duhem (ex-Logiciels & Services Duhem)
3, rue Pierre Haret - F-75009 Paris (France) - Tel. (+33) [0]149 700 455