Xcode AppIcon.appiconset — How to Export & Configure

If you've ever opened an Xcode project's Assets.xcassets folder in Finder, you've seen AppIcon.appiconset — the directory that holds your app's icon files and a Contents.json manifest. Understanding how this system works is essential for every iOS developer.

This tutorial covers the .appiconset structure from scratch, explains the Contents.json format, and shows how to automate the entire process.

What is AppIcon.appiconset?

An .appiconset is a special directory inside your Xcode asset catalog (.xcassets) that contains:

• Image files — PNG files at various sizes
• Contents.json — A manifest that maps each image to its intended use (size, scale, platform)

When Xcode builds your app, it reads Contents.json to know which image to use for each context (home screen, Spotlight, Settings, etc.).

The Contents.json Structure

Here's what a modern Contents.json looks like with the single-size approach (Apple’s asset-catalog workflow):

{
  "images": [
    {
      "filename": "AppIcon.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    }
  ],
  "info": {
    "author": "xcode",
    "version": 1
  }
}

This example configures one standard iOS 1024×1024 source image. It does not include separate dark/tinted artwork, another platform’s icon assets, or Icon Composer layers.

Legacy Multi-Size Format

Legacy multi-size catalogs reference individual image files for the particular slots a target needs. Here is a shortened example:

{
  "images": [
    {
      "filename": "icon-20@2x.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "20x20"
    },
    {
      "filename": "icon-20@3x.png",
      "idiom": "iphone",
      "scale": "3x",
      "size": "20x20"
    },
    {
      "filename": "icon-29@2x.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "29x29"
    }
  ]
}

Each entry specifies the idiom (iphone, ipad, etc.), the scale (1x, 2x, 3x), and the base size in points. The filename links to the actual PNG in the same directory.

Step-by-Step: Manual Setup

Step 1: Prepare Your Icon

For the standard iOS raster appearance, start with an opaque 1024×1024px PNG. Do not bake in rounded corners (iOS applies the system mask automatically). Verify the exported color profile and preview the actual image on your supported displays. Designing in Figma? Our Figma to Xcode app icon export tutorial covers the exact export settings.

Step 2: Open Assets.xcassets

In Xcode, navigate to your project's Assets.xcassets file in the Project Navigator (left sidebar). Click on AppIcon.

Step 3: Drag & Drop (Single Size)

Choose "Single Size" for iOS in the Attributes Inspector, then drag your 1024×1024 image into the standard appearance image well. Configure other appearances separately when provided.

Step 4: Verify

Build your project (⌘B) and check the simulator. Your icon should appear on the home screen, in Spotlight, and in Settings.

Step-by-Step: Legacy Multi-Size Setup

If you need individual sizes (for older Xcode versions or maximum control):

Step 1: Prepare the Sizes Your Target Needs

For a legacy multi-size catalog, prepare the files referenced by your target. The table below shows selected examples. Our free iOS icon size calculator lists selected reference slots with their pixel dimensions if you'd rather not memorize the table:

Filename	Size (px)	Purpose
icon-20@2x.png	40×40	iPhone Notification @2x
icon-20@3x.png	60×60	iPhone Notification @3x
icon-29@2x.png	58×58	iPhone Settings @2x
icon-29@3x.png	87×87	iPhone Settings @3x
icon-40@2x.png	80×80	iPhone Spotlight @2x
icon-40@3x.png	120×120	iPhone Spotlight @3x
icon-60@2x.png	120×120	iPhone App @2x
icon-60@3x.png	180×180	iPhone App @3x
icon-20.png	20×20	iPad Notification @1x
icon-20@2x-ipad.png	40×40	iPad Notification @2x
icon-29.png	29×29	iPad Settings @1x
icon-29@2x-ipad.png	58×58	iPad Settings @2x
icon-40.png	40×40	iPad Spotlight @1x
icon-40@2x-ipad.png	80×80	iPad Spotlight @2x
icon-76.png	76×76	iPad App @1x
icon-76@2x.png	152×152	iPad App @2x
icon-83.5@2x.png	167×167	iPad Pro App @2x
icon-1024.png	1024×1024	App Store

That's 18 images. Generating them manually with an image editor or command-line tool like sips is tedious:

# macOS Terminal — resize with sips
sips -z 180 180 master.png --out icon-60@3x.png
sips -z 120 120 master.png --out icon-60@2x.png
sips -z 87 87 master.png --out icon-29@3x.png
# ... repeat for all sizes

Step 2: Write Contents.json

Create the Contents.json file in the AppIcon.appiconset directory, mapping each filename to its idiom, size, and scale.

Step 3: Replace in Xcode

Replace the entire AppIcon.appiconset directory in your project with your new version containing all the resized images and the updated Contents.json.

Keep a recoverable copy of the old catalog and validate the new files before replacing it. Export convenience does not remove the need to inspect the target’s actual result.

Common Errors

"The app icon set does not have an image for size X"

This Xcode warning means Contents.json references a size that has no matching image file. Either the filename is wrong, the image is missing, or the size/scale combination doesn't match.

"The icon file must not contain alpha"

For the standard iOS raster appearance, flatten the artwork against the intended opaque background in an image editor. Verify the resulting file rather than assuming a PNG format conversion removes alpha.

# Read-only check of the exported image
sips -g pixelWidth -g pixelHeight -g hasAlpha icon-1024.png

"The app icon set does not have a valid image"

This usually means the image dimensions don't match what Contents.json declares. Double-check pixel dimensions with sips -g pixelWidth -g pixelHeight icon.png.

Summary

Use Single Size for a standard iOS source, or provide the particular legacy slots your target needs. Keep the filenames and dimensions consistent and inspect the installed result. There is no universal 18-image requirement for every project.

What About Xcode 26 and Icon Composer?

With Xcode 26, Apple introduced a new Icon Composer tool that outputs a single .icon file instead of the traditional .appiconset directory. Icon Composer supports layered Liquid Glass icons. For iOS and macOS, its appearance controls are Default, Dark and Mono; Mono includes clear and tinted variants. watchOS does not expose the same appearance choices.

To use it: Xcode → Open Developer Tool → Icon Composer. Design your layers, save as a .icon file, and drag it into your project. Configure and validate the platforms supported by that document; it does not replace every platform’s asset workflow. For more context on platform and appearance variants, see our guide to iOS 26 Liquid Glass app icons.

The .appiconset asset-catalog workflow remains available. For supported targets, adding an Icon Composer .icon file makes it the app-icon source. Keep the asset-catalog workflow if you want to retain its existing artwork on earlier OS releases.

IconBundlr combines generation and its iOS catalog export. Review the actual artwork and target integration; there is no fixed end-to-end completion-time guarantee.

Sources

• Apple Developer Docs — Configuring Your App Icon
• Apple Developer Docs — Icon Composer
• Apple HIG — App Icons
• Use Your Loaf — Xcode 14 Single-Size App Icons

Related: iOS App Icon Sizes: Source Images and Legacy References | Make an App Icon Without a Designer | App Store Icon Rejection Reasons & Fixes