ICO (Windows Icon)

An ICO file is a small directory of images: the same icon drawn at several sizes and color depths, for example 16x16, 32x32, 48x48 and 256x256. Windows picks the entry that best matches the size it needs (taskbar, Explorer, title bar, high-DPI screens). Each entry is either a BMP-style bitmap with a transparency mask or a complete PNG file.

ICO is used for Windows application and file icons and for favicon.ico, the site icon browsers request from the root of a web server. A CUR file is the same structure with type 2 and a hotspot (the click point) per entry instead of planes and bit depth. Animated cursors (.ani) are a different, RIFF-based format that contains ICO/CUR frames.

When to use ICO#

• Use for Windows program icons (.exe resources), shortcut and file-type icons, and static mouse cursors (.cur).
• Use for favicon.ico when you want one file that every browser and tool finds without any <link> tag.
• Avoid as a general image format: it’s limited to 256x256 per entry and has no metadata.
• Avoid for modern web icons when you control the HTML: a PNG or SVG favicon with <link rel="icon"> plus an apple-touch-icon PNG covers current browsers.

File structure#

An ICO file has 3 parts: a 6-byte ICONDIR header, one 16-byte ICONDIRENTRY per image, and the image data. All integers are little-endian.

00 00                     reserved, must be 0
01 00                     type: 1 = icon (ICO), 2 = cursor (CUR)
01 00                     number of images: 1
-- ICONDIRENTRY #1 --
20                        width: 32 (0 means 256)
20                        height: 32 (0 means 256)
00                        colors in palette: 0 (no palette)
00                        reserved
01 00                     ICO: color planes (0 or 1)   CUR: hotspot X
20 00                     ICO: bits per pixel: 32      CUR: hotspot Y
A8 10 00 00               size of image data: 4264 bytes
16 00 00 00               offset of image data: 22
-- image data at offset 22 --
28 00 00 00               BITMAPINFOHEADER size: 40
20 00 00 00               width: 32
40 00 00 00               height: 64 (2 x 32: color bitmap + AND mask)
01 00 20 00               planes 1, 32 bits per pixel
00 00 00 00 ...           compression BI_RGB, then 32x32x4 pixel bytes and a 32x32 1-bit mask

ICONDIR#

ICONDIRENTRY#

The directory values are hints. Decoders should trust the size and bit depth in the image data itself, because many tools write 0 for planes and bit count.

Image data: BMP or PNG#

Each entry’s data is one of 2 things:

• PNG: a complete PNG file, starting with 89 50 4E 47. Supported since Windows Vista. Use 32-bit RGBA. Microsoft recommends PNG only for 256x256 entries, where it saves the most space.
• BMP/DIB: a BMP without the 14-byte BITMAPFILEHEADER: a BITMAPINFOHEADER (40 bytes), a palette for 1, 4 and 8 bpp, the color (XOR) bitmap and a 1-bit AND mask. The header’s height is twice the icon height because it covers both bitmaps. Rows are stored bottom-up and padded to 4 bytes.

The AND mask marks transparent pixels (1 = transparent) for 1-24 bpp images. 32 bpp entries carry an 8-bit alpha channel, and the mask is still present for old software.

Icons in EXE and DLL files#

Inside a Windows executable the icon is split into resources: one RT_GROUP_ICON resource holds the directory and each image is a separate RT_ICON resource. The group entry (GRPICONDIRENTRY) is 14 bytes: it has a 2-byte resource ID where the file format has the 4-byte offset. Tools that “extract icons” from an EXE rebuild an ICO file from these resources.

Sizes to include#

Draw the small sizes by hand or at least sharpen them: a 256x256 icon scaled down to 16x16 is often blurry. Store 256x256 as PNG and the smaller sizes as 32-bit BMP for the best compatibility.

Specifications and documentation#

• Icons (Win32 technical article) (Microsoft): ICONDIR, ICONDIRENTRY, image data and icon resources
• About Cursors (Microsoft): cursors and hotspots
• Icons in the Windows UX guidelines (Microsoft): which sizes to draw
• PNG images in icons, and why only for 256x256 (The Old New Thing)
• image/vnd.microsoft.icon (IANA media type registration)
• ICO file format on Wikipedia

Software that opens ICO files#

Libraries#

Open-source libraries that read and write ICO. See all ICO libraries for a comparison.

Related formats#

• PNG: the image data of large icon entries; also used directly as a favicon
• BMP: small icon entries are BMP bitmaps without the file header
• ICNS: the macOS icon format, also a set of sizes in one file
• SVG: scalable favicons in modern browsers