Transloadit

What is an ICNS File?

An ICNS file is an Apple container for application icon resources. It can hold multiple icon dimensions, resolutions, and pixel representations used by macOS.

How ICNS Files work

An ICNS file groups the representations of one macOS icon for different display sizes and pixel densities. As implemented in Pillow’s reader, the file begins with the four bytes icns and a big-endian total length, followed by elements that each start with a four-character type code and a length. The type code identifies the representation: ic07 is the 128-point icon, for example, and ic10 the 512-point icon at 2x scale. Apple’s tooling builds the file from a folder with the .iconset extension that contains PNGs named by point size and scale. The iconutil command converts that folder into an ICNS file and back, and Apple’s archived 2012 guidance says Xcode 4.4 converts an iconset folder in a project automatically when the project is built. The bundle’s Info.plist names the icon file through the CFBundleIconFile key.

Key facts

  1. Which sizes belong in the file? Apple’s iconset convention uses five point sizes (16, 32, 128, 256, and 512), each at standard and @2x scale, so the largest image is 1024 by 1024 pixels and is named icon_512x512@2x.png. The set does not have to be complete: Apple’s guidance says the system chooses the best representation for sizes you do not supply. It also says icon_16x16@2x.png and icon_32x32.png are not equivalent although they have the same pixel count, because they appear at different sizes on screen and may need different detail. This guidance dates from 2012 and is in Apple’s documentation archive.
  2. What is inside each element? It depends on the type code, so a parser has to handle more than one payload form. In Pillow’s reader, the ic07 to ic14 and icp4 to icp6 elements each hold a complete PNG or JPEG 2000 image, while older types such as is32 and il32 hold RGB data, either raw or run-length encoded, with the alpha channel in a separate 8-bit mask element such as s8mk or l8mk. This matters for tools that reuse an ICNS file as an image source: electron-builder’s documentation says it extracts the largest embedded PNG frame when an ICNS file is the icon source for another platform. One user reported a Linux build that stopped with ‘Could not extract a PNG frame from ICNS file’ after the tool changed its icon converter, and worked around it by supplying a PNG for the Linux build. The report does not establish what in that file caused the failure, and a maintainer later said a new release of the converter should fix it.
  3. How do I create or inspect one? On macOS, iconutil -c icns converts an .iconset folder to an ICNS file and iconutil -c iconset converts an ICNS file back into its PNGs; Apple’s guidance says the iconset images must be square, with dimensions that match their file names. Off macOS, Pillow can write ICNS files on any operating system since version 8.3.0. Its writer scales the image you save to a square at each size you do not pass through append_images, and its save code does not check that the source is square or 1024 pixels wide. It matches the images in append_images by pixel width, so two elements with the same pixel size share one image. It writes only the ic07 to ic14 elements, 32 to 1024 pixels wide: the 32-pixel image is stored as the 16-point icon at 2x scale, and there is no element for the 16-point or 32-point icon at standard scale. Apple’s guidance is to design the large icon first and then decide how to scale it down, adjusting an icon where needed for the size and pixel density at which it appears.

When ICNS Files matter

An ICNS file matters when a macOS application bundle is assembled outside Xcode’s asset pipeline, for example by a cross-platform packaging tool. You may not have to build the file yourself: electron-builder’s documentation says it uses a prebuilt .icns file as-is and can also convert a PNG or SVG source, generating every size from that one input. Supply your own file when your tool requires one or when you want to control the artwork at each size. Inside Xcode, Apple’s current documentation has you provide the app icon through an asset catalog or an Icon Composer file instead. Apple’s archived 2012 guidance says a complete set of sizes is recommended but not required: macOS chooses the best available representation for a size you leave out, which means that size is shown from artwork drawn for a different one.

Sources

Turn media knowledge into a working pipeline

Connect uploads, processing, AI, storage, and delivery through one declarative API — with the encoding stack, scaling, and format churn handled for you.

Try Transloadit for free