Using Xcode Asset Catalog to Add and Manage iOS App Icons

Desired Outcome

By the end of this guide you will have a fully configured AppIcon set inside Assets.xcassets that satisfies all iOS size requirements, passes Xcode’s build validation, and displays correctly on every supported device.

Prerequisites

• macOS with Xcode 15 or later installed.
• An iOS project that already contains an Assets.xcassets folder.
• PNG images for each required icon size (see table below).
• Knowledge of the iOS app icon size specifications.

App Icon Size Matrix

Device	Icon Size (px)	Scale
iPhone Notification	20	@2x
iPhone Settings	29	@2x
iPhone Spotlight	40	@2x
iPhone App	60	@3x
iPad Notification	20	@1x
iPad Settings	29	@1x
iPad Spotlight	40	@1x
iPad App	76	@1x
iPad Pro App	83	@2x
App Store	1024	@1x

Procedure

1. Open the Asset Catalog

   In Xcode’s Project Navigator, double‑click Assets.xcassets to view its contents.

2. Create a New App Icon Set

   Click the + button at the bottom of the catalog and choose App Icons & Launch Images → New iOS App Icon. Name the set AppIcon (or a custom name if you plan to use multiple sets).

3. Populate the Placeholders

   Each placeholder corresponds to a required size. Drag and drop the PNG file that matches the dimensions into the slot. Xcode will automatically generate @2x and @3x variants when you provide a single 1x image. If you already have @2x/@3x files, drop them directly into the matching slots.

   Example: For the iPhone App slot (60 px), drag AppIcon-60.png (60 × 60). Xcode will create [contact removed] (120 × 120) and [contact removed] (180 × 180) if they are missing.

4. Validate the Set

   After all placeholders are filled, Xcode shows a checkmark next to the set name. If any slot remains empty, a warning icon appears. Hover over the warning to see which sizes are missing.

5. Build the Project

   Run Product → Build (⌘B). Xcode compiles the asset catalog and generates the AppIcon.appiconset bundle inside the app’s Resources folder. Build warnings related to the asset catalog appear in the Issue Navigator.

6. Archive for Distribution

   Choose Product → Archive. If the asset catalog is incomplete, the archive process fails with an error such as “AppIcon is missing required images.” Resolve any warnings before retrying.

7. Verify on Device

   Install the built app on a simulator or physical device. Open Settings → General → About → Your App and confirm the icon matches the 20 × 20 placeholder you supplied. The icon should appear crisp on all retina and non‑retina screens.

Expected Checks

• Issue Navigator shows zero asset‑catalog warnings after a clean build.
• Archive completes without asset‑related errors.
• Running the app on the simulator shows a correctly scaled icon on the home screen and in Settings.

Recovery Options

If Xcode reports missing or incorrectly sized images after you believe you have supplied all assets:

1. Clear Derived Data

   Open Xcode’s Organizer (⌘Shift+2), select the project, and click Delete under Derived Data. This removes cached asset bundles.

2. Clean the Build Folder

   In Xcode, choose Product → Clean Build Folder (⇧⌘K). This forces Xcode to regenerate all resources.

3. Re‑add the Images

   Delete the problematic placeholder from the catalog, then drag the PNG back in. Ensure the file name is unique within the catalog to avoid silent overwrites.

4. Check Color Space

   Open each PNG in Preview or ImageMagick and verify it is in the sRGB color space and not interlaced. Non‑sRGB images may appear distorted on older iOS versions.

Practical Verification Tip

After a successful build, locate the generated AppIcon.appiconset folder inside the app bundle (right‑click the app in Finder, Show Package Contents, navigate to Contents/Resources). Open the Contents.json file and confirm each required key (e.g., [contact removed]) is present. This manual check guarantees that Xcode has produced the correct asset bundle before deployment.