APPICON.APPICONSET
AppIcon.appiconset, structure and sizes explained.
AppIcon.appiconset is the folder in an Xcode asset catalog that holds iOS app icons: a Contents.json manifest plus PNGs named by device idiom, point size and scale. This page walks through the structure, the full size list, the Xcode import steps and how to troubleshoot a missing icon; if you just want the files, the icon generator at the end produces a complete set in one click.
Open the icon generator (iOS tab)The generator’s iOS tab outputs AppIcon.appiconset (with Contents.json). Everything runs locally in your browser — no upload.
What is AppIcon.appiconset?
In Xcode, app icons are not loose PNGs but a single asset folder named AppIcon.appiconset. It has two parts: the Contents.json manifest and a set of bitmaps named by device idiom, point size and scale. Xcode reads Contents.json to map each image to the right device and context (home screen, Spotlight, Settings, App Store, etc.). Drop the folder into Assets.xcassets and the project picks it up.
iOS icon size chart (current spec)
The full list a universal iOS app needs; point size × scale = pixels.
| Idiom (device) | Point size | Scale | Pixels | Filename |
|---|---|---|---|---|
| ipad | 20x20 | 1x | 20 | icon-20.png |
| iphone | 20x20 | 2x | 40 | icon-20@2x.png |
| ipad | 20x20 | 2x | 40 | icon-20@2x.png |
| iphone | 20x20 | 3x | 60 | icon-20@3x.png |
| ipad | 29x29 | 1x | 29 | icon-29.png |
| iphone | 29x29 | 2x | 58 | icon-29@2x.png |
| ipad | 29x29 | 2x | 58 | icon-29@2x.png |
| iphone | 29x29 | 3x | 87 | icon-29@3x.png |
| iphone | 40x40 | 2x | 80 | icon-40@2x.png |
| ipad | 40x40 | 2x | 80 | icon-40@2x.png |
| iphone | 40x40 | 3x | 120 | icon-40@3x.png |
| iphone | 60x60 | 2x | 120 | icon-60@2x.png |
| iphone | 60x60 | 3x | 180 | icon-60@3x.png |
| ipad | 76x76 | 1x | 76 | icon-76.png |
| ipad | 76x76 | 2x | 152 | icon-76@2x.png |
| ipad | 83.5x83.5 | 2x | 167 | icon-83.5@2x.png |
| ios-marketing | 1024x1024 | 1x | 1024 | icon-1024.png |
What Contents.json looks like
Contents.json maps each idiom / size / scale to a filename via the images array, with info for version and author. Here is a trimmed example matching this tool’s output:
{
"images" : [
{ "idiom" : "iphone", "size" : "20x20", "scale" : "2x", "filename" : "icon-20@2x.png" },
{ "idiom" : "iphone", "size" : "60x60", "scale" : "3x", "filename" : "icon-60@3x.png" },
{ "idiom" : "ipad", "size" : "76x76", "scale" : "2x", "filename" : "icon-76@2x.png" },
{ "idiom" : "ios-marketing", "size" : "1024x1024", "scale" : "1x", "filename" : "icon-1024.png" }
],
"info" : { "version" : 1, "author" : "tushuo" }
}Each filename must match an actual PNG in the folder; one image can serve multiple idioms (e.g. 40@2x is used for both iPhone and iPad Spotlight).
When the icon is missing or the build fails
Almost every iOS icon problem comes down to one of three things: the filename, the pixel size, or the App Icon name. Work through the table below and you will find it.
| Symptom | Cause | Fix |
|---|---|---|
| Blank home screen icon / generic placeholder | The App Icon name checked in the target does not match the folder name | Name the folder AppIcon.appiconset and confirm the name is also AppIcon under Target → General |
| Build fails with “unassigned child” | A filename in Contents.json points to a file that does not exist | Check every filename against the PNGs in the folder; letter case must match exactly |
| Edges look cropped / wrong corner radius | The PNG already has rounded corners or padding and the system masks it again | Supply an opaque square full-bleed image with no rounding or shadow; the system applies the shape |
| App Store rejects the 1024 upload | The marketing icon has an alpha channel or is not exactly 1024x1024 | Export an RGB PNG without alpha at exactly 1024x1024 |
| Icon changed but the simulator still shows the old one | Asset Catalog caching | Run Product → Clean Build Folder and rebuild, or delete AppIcon and drag it back in |
How to import into Xcode
- Download the ZIP and unzip it to get the AppIcon.appiconset folder.
- Open your project in Xcode and locate Assets.xcassets.
- Drag the whole AppIcon.appiconset folder into Assets.xcassets (replace the existing AppIcon).
- Under Target → General → App Icons and Launch Screen, confirm the App Icon name is AppIcon.
- Run on a simulator / device — the home screen icon updates; the 1024 marketing image is used for App Store uploads.
FAQ
Can I skip Contents.json?
No. Without it Xcode cannot map PNGs to idiom / size / scale, and the asset catalog will error or show no icon. It is the index of the appiconset.
Why do some sizes look duplicated (e.g. 40@2x and 60@2x are both 120px)?
Different point sizes, same pixels: 40pt@2x and 60pt@2x are both 120px but serve different contexts (Spotlight vs home screen). They are two entries in Contents.json that can point to the same file.
Do I need separate icons for dark / tinted mode?
Dark and tinted appearances are optional since iOS 18. Declare them via appearances in the same Contents.json, or keep separate AppIcon-dark / AppIcon-tinted folders as this tool does.
Are my images uploaded to a server?
No. Generation and zipping happen entirely in your browser; the source image never leaves your device.