Tutorial

Xcode AppIcon.appiconset — How to Export & Configure

February 10, 2026 · 6 min read

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 (introduced in Xcode 14):

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

This is the simplest configuration — a single 1024×1024 image from which Xcode generates all needed sizes at compile time.

Legacy Multi-Size Format

Before Xcode 14, you needed to provide every size individually. Here's a snippet of what that looked like:

{
  "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"
    },
    // ... 15+ more entries
  ]
}

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

Start with a 1024×1024px PNG. No transparency. No rounded corners (iOS applies the squircle mask automatically). Apple recommends Display P3 (wide-gamut) color space for greater vibrancy, with sRGB as a fallback.

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)

If you're using Xcode 14+ with the single-size approach, simply drag your 1024×1024 image into the "All Sizes" slot. Choose "Single Size" in the Attributes Inspector. Done.

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: Generate All Sizes

From your 1024×1024 master icon, you need to generate these files:

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.

This manual process is the #1 reason developers procrastinate on their app icon. It's not the design that's painful — it's the export.

One-Click Xcode Export

IconBundlr generates your icon and exports a complete .appiconset folder — Contents.json, all 19 sizes, ready to drag into Xcode. Zero manual resizing.

Try IconBundlr Free →

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"

App Store icons cannot have transparency. Open your PNG in Preview → File → Export → uncheck "Alpha". Or in Terminal:

# Remove alpha channel
sips -s format png --setProperty formatOptions 100 icon-1024.png --out icon-1024-no-alpha.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

The AppIcon.appiconset system is straightforward in concept but tedious in practice. If you're using Xcode 14+, the single-size approach simplifies everything to one drag-and-drop. For legacy projects or maximum control, you'll need all 18+ images and a correct Contents.json.

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 multi-layered, Liquid Glass icons with four appearance modes (Default, Dark, Clear, Tinted).

To use it: Xcode → Open Developer Tool → Icon Composer. Design your layers, save as a .icon file, and drag it into your project. Xcode 26 generates all platform variants automatically from this single file.

The .appiconset format still works in Xcode 26 for backward compatibility, but Apple is encouraging the new .icon format going forward.

Either way, tools like IconBundlr can handle both the generation and the export — turning a 30-minute task into a 30-second one.