Mastering App Icons in Flutter: A Guide to `flutter_launcher_icons` and Beyond

Your app icon is the first thing users see—it’s your digital storefront sign. But if you’ve ever tried to manage icons for both Android and iOS in Flutter, you know it can be a frustrating process of resizing, renaming, and placing files in multiple directories. Doing this manually is error-prone and time-consuming.

Thankfully, the Flutter community has a great solution: the flutter_launcher_icons package. This guide will walk you through using this tool and understanding app icon requirements on both platforms.

The Problem: A Multi-Platform Icon Nightmare

Android and iOS have different requirements for app icons. They need different file names, sizes, and folder structures.

• Android primarily uses mipmap- folders (hdpi, mdpi, xhdpi, etc.) and expects specific filenames like ic_launcher.png.
• iOS uses an Assets.xcassets app icon set with specific sizes for the app, notifications, and settings.

Manually creating and updating dozens of image files isn’t scalable. This is where automation helps.

Introducing flutter_launcher_icons

flutter_launcher_icons is a command-line tool that automates icon generation. You provide one high-resolution source image, and it generates all the correctly sized and named variants for Android and iOS.

Step 1: Setup and Configuration

First, add the package to your pubspec.yaml under dev_dependencies.

dev_dependencies:
  flutter_launcher_icons: ^0.13.1

Next, add a flutter_launcher_icons configuration section in the same file.

flutter_launcher_icons:
  android: true
  ios: true
  image_path: "assets/icons/app_icon.png"
  image_path_android: "assets/icons/android_icon.png" # Optional override
  image_path_ios: "assets/icons/ios_icon.png"         # Optional override
  # Optional: Remove background for adaptive icons (Android 8.0+)
  android_adaptive_icon_foreground: "assets/icons/adaptive_foreground.png"
  android_adaptive_icon_background: "assets/icons/adaptive_background.png"

Step 2: Preparing Your Source Image

Your source image should be:

• High resolution: At least 1024x1024 pixels.
• Simple and recognizable: Icons are small. Avoid fine detail.
• Square: The tool requires a square image.
• Without transparency for Android (usually): Android’s legacy launcher icons typically use a solid background. Use the adaptive icon settings if you want transparency.

Step 3: Generating the Icons

Run the package from your terminal:

flutter pub get
flutter pub run flutter_launcher_icons:main

The package will:

1. Process your source image.
2. Generate all Android variants and place them in android/app/src/main/res/mipmap-*/.
3. Generate the iOS icon set and integrate it into your ios/Runner/Assets.xcassets/AppIcon.appiconset.

Step 4: Verifying and Building

Always verify the output:

• Android: Check the mipmap folders in android/app/src/main/res/.
• iOS: Open your project in Xcode (open ios/Runner.xcworkspace), navigate to Runner > Assets.xcassets > AppIcon, and ensure all slots are filled.

Finally, do a clean rebuild:

flutter clean
flutter run

Common Pitfalls and How to Avoid Them

1. “My icon looks blurry on one platform!”

   • Cause: You likely provided a source image that was too small. The tool scales it up for the largest required size, causing pixelation.
   • Fix: Always start with an image that is larger than the largest required icon size (1024x1024 for iOS).

2. “The command runs but nothing changes!”

   • Cause: Cached icons.
   • Fix: Always run flutter clean after generating new icons. For iOS, you may also need to delete the app from your simulator/device and rebuild.

3. “I get an error about the image path!”

   • Cause: The image_path in your config doesn’t point to a valid file, or the file isn’t square.
   • Fix: Double-check the path relative to your project root. Confirm the image is square.

4. “iOS icons are generated but don’t show up in Xcode!”

   • Cause: This sometimes happens if the Contents.json file becomes corrupted.
   • Fix: In Xcode, right-click the AppIcon set and select “Delete”. Re-run flutter pub run flutter_launcher_icons:main.

Going Beyond: Adaptive and Custom Icons

Android Adaptive Icons

For Android 8.0 (API 26) and above, you can create adaptive icons with separate foreground and background layers. Configure them using the android_adaptive_icon_foreground and android_adaptive_icon_background settings.

Handling iOS Complications

While flutter_launcher_icons handles the standard app icon, remember that iOS also uses icons for Spotlight search, Settings, and Notifications. The package manages these automatically. However, if you need to set a different icon for iPad or macOS, you’ll need to manually add additional icon sets in Xcode.

Best Practices for a Polished Workflow

1. Version Control: Add the generated native directories to your .gitignore. Only commit your source assets/icons/app_icon.png and your pubspec.yaml configuration.
2. Design First: Finalize your app icon design early.
3. Test on Real Devices: Icons can look different on various device screens and launchers.

By integrating flutter_launcher_icons into your workflow, you turn a tedious process into a single command. This lets you focus on building your app.