How to Set a Flutter Launcher Icon for Android and iOS: Complete Guide

Set a custom flutter launcher icon by using the flutter_launcher_icons package to automatically generate platform-specific assets, or manually replace the default icons in the Android mipmap directories and iOS Assets.xcassets folder.

Configuring a custom flutter launcher icon requires modifying platform-specific resource files that Flutter generates from templates in the flutter/flutter repository. While you can manually manage these assets, the recommended approach uses a dedicated Dart package to handle the resizing, naming conventions, and manifest updates for both Android and iOS simultaneously.

Understanding Flutter Launcher Icon Configuration

Flutter applications rely on native platform mechanisms to display launcher icons. According to the source templates in the flutter/flutter repository, these resources are stored in specific directories that the build systems expect:

• Android: Icons reside in android/app/src/main/res/mipmap-*/ directories (e.g., mipmap-mdpi, mipmap-hdpi) and are referenced in AndroidManifest.xml via android:icon="@mipmap/ic_launcher"
• iOS: Icons are stored in the asset catalog at ios/Runner/Assets.xcassets/AppIcon.appiconset/ and managed by the Xcode project configuration in ios/Runner.xcodeproj/project.pbxproj

Method 1: Using the flutter_launcher_icons Package (Recommended)

The flutter_launcher_icons package automates the generation of properly sized icons and updates the necessary configuration files. This method ensures your flutter launcher icon meets platform requirements without manual resizing.

Step 1: Add the Dependency

Add the package to your pubspec.yaml under dev_dependencies:

dev_dependencies:
  flutter_launcher_icons: ^0.13.2

Step 2: Configure pubspec.yaml

Define the flutter launcher icon configuration in the same pubspec.yaml file:

flutter_icons:
  android: true
  ios: true
  image_path: "assets/icon.png"
  # Optional: platform-specific overrides

  # android_icon: "assets/icon_android.png"

  # ios_icon: "assets/icon_ios.png"

The image_path should reference a high-resolution source image (minimum 1024×1024 pixels) located in your project assets.

Step 3: Generate the Icons

Run the generator commands from your project root:

flutter pub get
flutter pub run flutter_launcher_icons:main

This tool performs the following operations based on the Flutter template structure:

• Android: Creates mipmap-mdpi, mipmap-hdpi, mipmap-xhdpi, mipmap-xxhdpi, and mipmap-xxxhdpi directories under android/app/src/main/res/, placing scaled ic_launcher.png files in each
• Android Manifest: Ensures android/app/src/main/AndroidManifest.xml contains android:icon="@mipmap/ic_launcher"
• iOS: Populates ios/Runner/Assets.xcassets/AppIcon.appiconset/ with the required icon sizes (20×20pt, 29×29pt, 40×40pt, 60×60pt, 76×76pt, 83.5×83.5pt, and 1024×1024pt) and updates Contents.json
• Xcode Project: Configures ios/Runner.xcodeproj/project.pbxproj to set ASSETCATALOG_COMPILER_APPICON_NAME to AppIcon

Method 2: Manual Configuration

If you prefer not to use the automated package, you can manually replace the default flutter launcher icon assets.

Android Manual Setup

1. Prepare your icon in the following sizes and place them in the corresponding directories:

   • 48×48 px → android/app/src/main/res/mipmap-mdpi/ic_launcher.png
   • 72×72 px → android/app/src/main/res/mipmap-hdpi/ic_launcher.png
   • 96×96 px → android/app/src/main/res/mipmap-xhdpi/ic_launcher.png
   • 144×144 px → android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png
   • 192×192 px → android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png

2. Verify that android/app/src/main/AndroidManifest.xml references the correct icon:

<application
    android:name="${applicationName}"
    android:label="MyApp"
    android:icon="@mipmap/ic_launcher">
</application>

iOS Manual Setup

1. Open ios/Runner.xcworkspace in Xcode.
2. Navigate to Runner → Assets.xcassets → AppIcon.appiconset.
3. Replace the placeholder images with your own assets, maintaining the exact filenames specified in Contents.json.
4. Ensure the Xcode project file ios/Runner.xcodeproj/project.pbxproj contains the build setting:

ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;

Key Files in the Flutter Repository

The default project structure generated by Flutter comes from templates in the flutter/flutter repository. Understanding these source files helps when troubleshooting icon issues:

• [android/app/src/main/AndroidManifest.xml](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/templates/app/android.tmpl/app/src/main/AndroidManifest.xml.tmpl): Template for the Android manifest that declares the launcher icon via android:icon="@mipmap/ic_launcher"
• [ios/Runner/Assets.xcassets/AppIcon.appiconset/Contents.json](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/templates/app/ios.tmpl/Runner/Assets.xcassets/AppIcon.appiconset/Contents.json): Defines the required icon sizes and filenames for the iOS asset catalog
• ios/Runner.xcodeproj/project.pbxproj: Template for the Xcode project configuration that sets ASSETCATALOG_COMPILER_APPICON_NAME to AppIcon

Summary

• Use the flutter_launcher_icons package to automatically generate properly sized icons for both Android and iOS from a single high-resolution source image.
• Android stores icons in mipmap-* density folders under android/app/src/main/res/ and references them in AndroidManifest.xml.
• iOS stores icons in the AppIcon.appiconset asset catalog under ios/Runner/Assets.xcassets/ and manages them via the Xcode project file.
• Manual configuration requires preparing multiple image sizes and ensuring platform-specific configuration files reference the correct asset names.

Frequently Asked Questions

What is the recommended image size for a flutter launcher icon source file?

Use a minimum of 1024×1024 pixels for your source image when using the flutter_launcher_icons package. This resolution ensures the tool can generate high-quality downscaled versions for all required densities, including the 1024×1024 App Store icon for iOS and the 192×192 xxxhdpi icon for Android.

Can I use different icons for Android and iOS in Flutter?

Yes. In your pubspec.yaml, specify platform-specific paths using the android_icon and ios_icon properties instead of the single image_path. Alternatively, set android: true or ios: true to false if you want to customize only one platform while leaving the other with default assets.

Why isn't my flutter launcher icon updating on my device?

This typically occurs due to caching or incomplete asset replacement. First, run flutter clean to clear the build cache, then rebuild the app. On Android, ensure you replaced the icons in all five mipmap-* directories. On iOS, verify that the Assets.xcassets/AppIcon.appiconset contains all required sizes and that the Xcode project references AppIcon in the build settings.

Where does flutter_launcher_icons store the generated iOS icons?

The package stores generated iOS icons in ios/Runner/Assets.xcassets/AppIcon.appiconset/. It creates PNG files for each required size (20×20pt, 29×29pt, 40×40pt, 60×60pt, 76×76pt, 83.5×83.5pt, and 1024×1024pt) and updates the Contents.json file to register these assets with the Xcode build system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}