Table of Contents

ICO

ICO is the Windows icon container format. It is designed to carry icon image data rather than act as a general-purpose picture format, and ImageSharp exposes both image-level and frame-level ICO metadata because individual embedded icon images can vary.

ImageSharp exposes ICO-specific APIs through IcoEncoder, IcoMetadata, and IcoFrameMetadata.

Format Characteristics

ICO is best thought of as a container for one or more icon images.

An ICO file can contain multiple frames for different icon sizes and bit depths. That lets Windows and other consumers choose the most appropriate embedded image for a particular scale or display context. A single-frame ICO can work, but multi-size icon assets are often more useful in real applications.

Frames can be stored using BMP-style data or PNG-compressed data. PNG-compressed icon frames are common for larger or more detailed icons because they can preserve alpha and reduce file size. BMP-style frames can still matter for older compatibility workflows.

The encoded width and height are part of the frame metadata, not just a consequence of the decoded ImageSharp frame size. When generating icons, keep frame metadata aligned with the asset sizes your target platform expects.

A few practical implications:

  • Existing ICO files can contain one or more embedded icon images.
  • ImageSharp exposes per-frame icon details such as Compression, BmpBitsPerPixel, EncodingWidth, and EncodingHeight.
  • Frame compression is represented through IconFrameCompression.
  • ICO is a Windows asset format, not a general interchange format for ordinary images.

Save as ICO

Use IcoEncoder when you want Windows icon output:

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Ico;
using SixLabors.ImageSharp.Formats.Icon;
using SixLabors.ImageSharp.PixelFormats;

using Image<Rgba32> image = Image.Load<Rgba32>("icon-source.png");

IcoFrameMetadata frameMetadata = image.Frames.RootFrame.Metadata.GetIcoMetadata();
frameMetadata.Compression = IconFrameCompression.Png;
frameMetadata.EncodingWidth = 64;
frameMetadata.EncodingHeight = 64;

image.Save("app.ico", new IcoEncoder());

ICO Frame Metadata

The most useful ICO-specific values live on IcoFrameMetadata:

  • Compression controls whether the encoded frame uses BMP or PNG storage.
  • BmpBitsPerPixel controls the BMP bit depth when the frame is stored as BMP.
  • EncodingWidth and EncodingHeight describe the encoded icon dimensions for that frame.

IcoMetadata mirrors the root frame's compression, bit depth, and color-table information at the image level.

Treat each frame as an icon candidate, not just a page in an image sequence. If you create a multi-frame ICO, inspect every frame's dimensions, compression, and bit depth before saving.

Read ICO Metadata

Use Image.Identify() when you want to inspect the icon container without decoding every embedded image:

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Ico;

ImageInfo info = Image.Identify("app.ico");

Console.WriteLine($"Embedded images: {info.FrameMetadataCollection.Count}");

IcoMetadata icoMetadata = info.Metadata.GetIcoMetadata();
IcoFrameMetadata firstFrame = info.FrameMetadataCollection[0].GetIcoMetadata();

Console.WriteLine(icoMetadata.Compression);
Console.WriteLine(firstFrame.EncodingWidth);
Console.WriteLine(firstFrame.EncodingHeight);

When to Use ICO

ICO is usually worth considering when:

  • You need a Windows icon file.
  • You care about icon-specific frame metadata such as encoded icon dimensions or frame compression.

ICO is usually a poor fit when:

  • You are storing ordinary images rather than icons.
  • You want a broadly portable web or application image format.

For ordinary image delivery or storage, PNG, WebP, and JPEG are usually better choices.

Practical Guidance

  • Include the sizes your target platform expects instead of assuming one frame is enough.
  • Inspect frame metadata when converting existing icons so dimensions and compression remain intentional.
  • Use ICO for Windows icon assets, not general image storage.
  • Keep source artwork separately; generated icon files are usually deployment artifacts.
Edit this page