Chromium’s icons

Asset catalogs for the app icon and document icon badge

Mac Chromium stores its app icon and document icon badge in an asset catalog. Unlike iOS Chromium, which compiles an .xcassets directory into a .car file at build time, Mac Chromium has the .car file pre-built and checked in. This is done because (unlike on iOS) the asset catalog file only holds three items and thus isn’t often changing, and because of internal technical constraints in tooling. This may change in the future.

Chromium’s asset catalog contains three logical items:

1. A collection of assets (Icon Image, MultiSized Image, PackedImage) named AppIcon used for the app icon on macOS releases prior to macOS 26.
2. A collection of assets (Color, Image, IconGroup, IconImageStack, Named Gradient, Vector) named AppIcon used for the app icon on macOS 26 and subsequent releases.
3. A collection of assets (Icon Image, MultiSized Image) named Icon used for badging documents using the UTTypeIcons/UTTypeIconBadgeName/UTTypeIconText Info.plist keys.

The sources for this catalog are an .xcassets directory as well as an .icon Icon Composer document package. These sources, as well as the compiled .car result, are checked into the //chrome/app/theme directory.

The current state of app icons (as of July 2025) is that Chrome compiles a “split app icon” asset catalog: the AppIcon bitmaps used for macOS releases prior to macOS 26 are those of the old, 2022-era app icon, while the AppIcon vectors used for macOS 26 and subsequent releases are of the new, 2025-era Icon Composer app icon. As users migrate to macOS 26 and subsequent releases, this will likely be revisited.

Compiling the asset catalog

To compile the asset catalog, invoke //tools/mac/icons/compile_car.py:

python3 tools/mac/icons/compile_car.py chrome/app/theme/chromium/mac/Assets.xcassets

(or the path to whichever .xcassets file you want to compile)

There is no need to specify the corresponding .icon file; its name will be derived from the name of the .xcassets file specified. The script will compile the two source files, and will put the files resulting from the asset catalog compilation into the directory containing the source files that were processed.

.icns files

While the app icon and document icon badge are stored in an asset catalog, .icns files are still required in certain circumstances (e.g. .dmg icons). When such icons are still required, this is the Chromium convention for their construction.

Sizes

.icns files contain multiple sizes of icons. Standard .icns files for Chromium contain icons of the following sizes:

Size	Type
16×16	'is32'/'s8mk'
32×32	'il32'/'l8mk'
128×128	'it32'/'t8mk'
256×256	'ic08' (PNG)
512×512	'ic09' (PNG)

Rationale

The rationale behind these choices is to avoid bugs in icon display. As noted in a bug, having @2x versions of the smaller icons causes blockiness on retina Macs, and in fact, sometimes just having @2x versions of icons would cause them to be preferred even when it doesn't make sense.

At least through macOS 10.11, using the modern ('icp4'–'icp6') types causes scrambling of the icons in display. If the old types work, why mess with them?

Source PNG files

Use whatever tools you want to create the PNG files, but please note that the dimensions of the images in the PNG files must match exactly the size indicated by their filename. This will be enforced by the makeicns2 tool below.

Construction

The tools for .icns construction can be found in //tools/mac/icons. Compile makeicns2 before you begin by following the directions in its header comment.

In addition, you will need optipng and advpng, which can be found in the optipng and advancecomp packages, respectively, in your favorite port manager.

To construct an .icns file:

1. Assemble a directory (.iconset) containing the five required sizes of icon, in PNG format: 16×16, 32×32, 128×128, 256×256, and 512×512, named 16.png, 32.png, 128.png, 256.png, and 512.png, respectively.
2. Process the .png files with:
   1. optipng -o7 -zm1-9
   2. advpng -z4 -i50
   3. png_fix.py
3. Create the .icns file with the makeicns2 you compiled: makeicns2 <name>.iconset

Historical tools

Tools historically used for .icns file construction and analysis can be found in //tools/mac/icons/additional_tools.