Flutter Launcher Icons

pub package pub points License CodeRabbit Pull Request Reviews

A maintained fork of fluttercommunity/flutter_launcher_icons. Thank you to @MarkOSullivan94 and all the original contributors for building the tool this continues. Bug reports, ideas, and pull requests are welcome here — see CONTRIBUTING.md.

A command-line tool that generates your Flutter app's launcher icons from a source image. Enable each platform with generate: true, with per-platform overrides for sources, names, and appearance variants. Full reference lives in doc/.

Why This Package

Compared with flutter_launcher_icons and icons_launcher:

  • Actively maintained! File any feature / bug reports, we'd love to keep improving this!
  • Modern icon variants — Android monochrome/round/notification layers, iOS 18+ dark/tinted appearances, liquid-glass .icon bundles on iOS/macOS, and PWA maskable/monochrome/shortcut/social images on web.
  • Flavors on every platform — sections or files, single --flavor runs, with flavored outputs (src/<flavor>/res, AppIcon-<flavor>, per-flavor web roots and Windows ICO names) instead of Android-only or multi-flavor flags.
  • Deep native wiring with safe cleanup — manifest, colors.xml, pbxproj/xcconfig, index.html/manifest.json, runner patches, plus stale-output sweeping, instead of emit-only assets.
  • Strict and predictable — unknown keys and type mismatches fail fast, and dart run launcher_icons:generate emits a template covering every key.

Migrating from Flutter_launcher_icons

This fork has diverged heavily and is still volatile: most features from flutter_launcher_icons still exist, but many are renamed or have different semantics (e.g. flat <platform>: sections with generate: true instead of shorthand values, image_path instead of image_path_android/image_path_ios, split theme_color_light/theme_color_dark on web). After running the new tool, check git diff carefully — and if any change still looks incorrect, please file an issue.

Quickstart

Add the dependency and generate a starter config:

dev_dependencies:
  launcher_icons: "^0.15.0"

dart run launcher_icons:generate

This writes launcher_icons.yaml in your project root. Or skip the file and configure inside pubspec.yaml — both work.

Then run the tool:

flutter pub get
dart run launcher_icons

Your config file must sit next to pubspec.yaml. The :generate command takes a file name, while the main command searches a folder:

dart run launcher_icons:generate -c my_icons.yaml
dart run launcher_icons -c .

Source Image

Use one high-resolution PNG — 1024×1024 recommended. Everything is downscaled from it (iOS needs the 1024px App Store icon), so starting smaller loses quality. JPG/JPEG/WebP are accepted for some inputs (e.g. Android adaptive layers, web sources). Raster outputs are PNG, plus the Windows and favicon .ico files, verbatim .xml vector drawables and the .svg favicon, liquid-glass .icon bundles, and patches to manifests, HTML, and Xcode/Gradle-adjacent project files.

SVG sources are supported, but the built-in renderer is beta quality: stick to basic shapes, paths, fills, strokes, and gradients. <text> elements generally do not render (convert text to outlines first), advanced features like filters, masks, patterns, and embedded images may be ignored or misrendered, and very thin strokes can glitch. Transparency is recovered by compositing, so semi-transparent edges can fringe slightly, and the SVG must declare dimensions (a viewBox or width and height). Simple logos are usually fine — but if the output doesn't match your editor, export PNGs externally (e.g. Figma, Inkscape, Illustrator at 1024px) and feed those in instead.

What Gets Generated

Platform Outputs Reference
Android legacy 48, 72, 96, 144, 192 (mipmap-mdpi → mipmap-xxxhdpi) Android
Android adaptive 108, 162, 216, 324, 432 foreground/background/monochrome (drawable-*) + mipmap-anydpi-v26 XML (PNG layers, or your own .xml vector drawables passed through verbatim) Android
Android notification 24, 36, 48, 72, 96 small icon (drawable-*) + FCM default_notification_icon manifest wiring Android
iOS 20 – 1024, plus optional dark, tinted, and liquid-glass .icon variants iOS
Web PWA 192, 512 (+ maskable, optional monochrome), 180px apple-touch-icon, optional 96px shortcut icons, optional 1200x630 Open Graph and 1200x600 Twitter images, favicon PNG (default 32) + multi-size ICO + optional verbatim SVG Web
Windows .ico with 16, 20, 24, 32, 40, 48, 64, 96, 128, 256px frames, plus MSIX tile / AppList assets and a manifest snippet Windows
macOS 16 – 1024 (@1x/@2x sets), plus an optional liquid-glass .icon bundle macOS
Linux hicolor tree (16–512), .desktop entries, opt-in snap/ packaging, window-icon runner patch Linux

Configuration

Top-level image_path is the default for every platform; any platform-level image_path overrides it. Paths are project-relative local files. At least one platform must set generate: true, and unknown keys or type mismatches fail instead of being ignored.

launcher_icons:
  image_path: "assets/icon/icon.png"
  android:
    generate: true
  ios:
    generate: true

Each platform page documents every key: config sources and flavors, Android, iOS, Web, Windows, macOS, Linux.

Flavors

Declare each variant as a launcher_icons-<flavor> section in your config file or pubspec.yaml, or as a launcher_icons-<flavor>.yaml file carrying that section. Each section stands alone with the same shape as launcher_icons: — declaring the same flavor twice is an error. Discovery is flat (no recursion).

launcher_icons-dev:
  image_path: "assets/icon/icon-dev.png"
  android:
    generate: true
launcher_icons-prod:
  image_path: "assets/icon/icon-prod.png"
  android:
    generate: true

dart run launcher_icons                  # every flavor
dart run launcher_icons --flavor dev     # one flavor (bare name)

Flavor outputs land in the flavored locations (src/<flavor>/res, AppIcon-<flavor>, per-flavor web output_path / Windows icon_filename, and so on). Details: Configuration and Flavors.

Command-Line Options

Two separate commands — their flags differ.

Main command (dart run launcher_icons):

Option Description
-h, --help Usage help
--version Tool version
-v, --verbose Verbose output
-c, --config <folder> Folder to search for config files. Defaults to .
-d, --dir <path> Project root. Defaults to the current directory
-f, --flavor <name> Run a single flavor (bare name)

Template generator (dart run launcher_icons:generate):

Option Description
-h, --help Usage help
--version Tool version
-o, --override Overwrite the output file
-c, --config <file> Output file name (must end .yaml). Defaults to launcher_icons.yaml

Exit codes: 0 success, 1 a platform failed, 2 bad config or CLI usage. A failed platform never reports success, and every platform runs before the command exits.

Troubleshooting

Old icon still shows after regenerating. The files are usually right and a cache is stale: flutter clean, uninstall the app from the device/emulator, rebuild. iOS: re-check Asset Catalog App Icon Set Name. Android flavors: delete leftover mipmap-anydpi-v26/ic_launcher.xml under src/main/ shadowing the flavor resources.

Anything else: open an issue.

Credits

Icon resizing via Brendan Duncan's image package. Full history and attributions in CHANGELOG.md and the upstream repository.

Libraries