flutter_launcher_iconsでFlutterのアプリアイコンを設定する｜adaptive iconとiOS 18対応の判断【2026年8月時点】

Flutterで作ったアプリのホーム画面アイコンは、AndroidとiOSでそれぞれ十数種類の寸法が要ります。flutter_launcher_iconsは、元画像1枚と数行の設定から全サイズを生成し、両OSのプロジェクトへ配置するコマンドラインツールです。2026年8月時点の最新は0.14.4で、公開は2025年6月10日、そこから更新は止まっています。一方で0.14.0はAndroid 13のテーマ対応アイコンとiOS 18のダーク・ティント表示に追いついており、流通する解説記事の多くはその前の書式のままです。本記事では設定の書き方、adaptive iconの寸法条件、iOS側の透過処理、更新が止まったパッケージの扱い方を一次情報から整理します。

まとめ：正方形1枚とYAMLの数行で両OS分を生成し、adaptiveとダークは別画像を用意する

設定の芯は3行です。dev_dependenciesにflutter_launcher_iconsを足し、pubspec.yamlの中にflutter_launcher_iconsという鍵のブロックを置き、image_pathに1024x1024pxの正方形PNGを指すだけで、AndroidとiOSの標準アイコンは揃います。実行コマンドは dart run flutter_launcher_icons のひとつだけで済みました。

ここから先が判断の分かれる領域になります。Androidのadaptive iconは、108x108dpのうち中央66x66dpしか常に見える保証がありません。標準のアイコンと同じ画像を前景に流用すると、円形マスクの端でロゴが切れます。前景は余白を含めて描き直し、テーマ対応アイコンを出すならadaptive_icon_monochromeで単色版をもう1枚渡してください。iOSはApp Storeが透過を受け付けないため remove_alpha_ios と background_color_ios の組で埋めます。

採否の要点は更新頻度です。安定版0.14.4は2025年6月10日から動いておらず、SDK制約はDart 3系の全域を許すため現行のFlutterでも起動しますが、将来のOS仕様変更に追随する保証はありません。単発の生成ツールとして割り切り、生成物をリポジトリへ含めて再現性を確保するのが受託案件では扱いやすい形になります。継続的な追随を求めるなら、更新の新しいicons_launcherを検討する余地が残ります。

launcher iconとIconsクラスは別物として切り分ける

「flutter icon」という検索語には、性質の異なる二つの要求が混ざっています。片方はホーム画面に並ぶアプリの顔を差し替えたい要求、もう片方はボタンや一覧に置く小さな絵柄を探す要求です。この二つは扱う層もツールもまったく別なので、先に切り分けておきます。

Icons.homeで並ぶ組み込みアイコンとホーム画面のアイコンの違い

Icons.home や Icons.settings のように書いて画面内に置くものは、Flutterに同梱されたMaterial Iconsのフォントから文字として描かれる絵柄です。色や大きさはウィジェットのプロパティで変えられ、ビルド構成にもOSのプロジェクトにも影響しません。一覧を探しているなら、参照先はMaterialのアイコンカタログになります。

これに対してランチャーアイコンは、OS側がホーム画面やアプリ一覧に描く画像です。Flutterのコードからは触れず、Androidなら res 配下のmipmap、iOSなら Assets.xcassets の中に置かれたPNGが実体になります。ここを手で並べる作業を省くのがflutter_launcher_iconsの役目です。

flutter_launcher_iconsが書き換えるファイルの場所

生成の結果はFlutterのDartコードではなく、ネイティブ側のプロジェクトへ直接書き込まれます。Androidでは res 配下の mipmap-hdpi から mipmap-xxxhdpi までへPNGが置かれ、adaptive iconを指定した場合はさらに mipmap-anydpi-v26 に ic_launcher.xml が作られます。この v26 という接尾辞は、adaptive iconがAPI 26から入った仕組みであることの表れです。

iOSでは Assets.xcassets の AppIcon.appiconset 配下のPNGと Contents.json が置き換わります。どちらもバージョン管理の対象なので、実行するとdiffが数十件並びました。初回は生成前の状態をコミットしておくと、差分を確認してから取り込めます。

flutter_launcher_iconsの導入と設定ブロックの書き方

dev_dependenciesへの追加とpubspec.yamlでの記述位置

このパッケージはビルド成果物に含める必要がないため、dependenciesではなくdev_dependenciesへ入れます。設定ブロックはpubspec.yamlの最上位、つまりflutterキーと同じ階層に置いてください。flutterキーの内側へ入れてしまうと解析の対象から外れます。

dev_dependencies:
  flutter_launcher_icons: ^0.14.4

flutter_launcher_icons:
  android: "ic_launcher"
  ios: true
  image_path: "assets/icon/app_icon.png"
  min_sdk_android: 21
  adaptive_icon_background: "#0B5FFF"
  adaptive_icon_foreground: "assets/icon/foreground.png"
  adaptive_icon_foreground_inset: 16
  adaptive_icon_monochrome: "assets/icon/monochrome.png"
  remove_alpha_ios: true
  background_color_ios: "#FFFFFF"

image_pathに渡す元画像は1024x1024pxの正方形PNGが基準です。縮小されるだけで拡大はされないため、小さい画像を渡すと全サイズがぼやけます。androidの値に文字列を書くと、その名前でリソースが作られ、既存のic_launcherを残したまま差し替えられました。単にtrueと書けば標準の名前を上書きします。

flutter_iconsから鍵名が変わった経緯と現在の書き方

設定ブロックの鍵は、もともと flutter_icons という名前でした。2023年4月15日の0.13.1で flutter_launcher_icons という名前も受け付けるようになり、以後の公式ドキュメントは後者で書かれています。日本語の解説記事は0.13.1より前に書かれたものが多く残っており、flutter_icons の表記が今も広く出回っています。

実行コマンドと設定ファイルを分けるflavorごとの運用方法

依存を取得したあと、生成は dart run flutter_launcher_icons を叩くだけです。開発版と本番版でアイコンを変えたい場合は、-f オプションで設定ファイルを指定します。

flutter pub get
dart run flutter_launcher_icons
dart run flutter_launcher_icons -f flutter_launcher_icons-staging.yaml

フレーバーごとにYAMLを分けておくと、検証版だけ隅に色帯を入れたアイコンにできます。端末のホーム画面に本番版と検証版が並んだとき、見分けがつかない状態は事故のもとでした。元画像はassets配下に置くため、参照の型安全化を併せて考えるならFlutterGenによるアセット管理の自動生成と同じディレクトリ設計へ寄せると管理が一本化します。

Android側でadaptive iconを崩さない寸法条件

108dpのうち66dpしか見えない前提で前景画像を用意する

adaptive iconは背景と前景の2枚のレイヤーで構成され、どちらも108x108dpの正方形として扱われます。実際に画面へ出るのは、そのうち中央の66x66dpだけです。四辺それぞれ18dpは、円形や角丸などランチャー側のマスク形状と、長押し時の視差効果のために予約されています。

ロゴ本体は48x48dpから66x66dpの範囲に収めるのが設計上の目安です。標準アイコン用の1024px画像を前景へ流用すると、ロゴが枠いっぱいに描かれているぶん端が確実に欠けます。前景用には、同じロゴを中央に小さく置き、周囲を透明にした画像を別途用意してください。

背景と前景を両方指定しないとadaptive iconにならない

adaptive_icon_background と adaptive_icon_foreground は、両方揃って初めて有効になります。片方だけ書いた場合、mipmap-anydpi-v26 の生成はされず、従来の正方形アイコンだけが出力されました。背景には16進のカラーコードか画像パスのどちらも渡せますが、単色を指定するほうがマスク形状に左右されず安定します。

前景の余白を設定側で稼ぎたい場合は、0.14.0で入った adaptive_icon_foreground_inset が使えます。数値を渡すと前景レイヤーを内側へ縮めて配置するため、画像を作り直さずに切れを回避できる場面があります。ただし縮小である以上ロゴの線は細くなるので、最終的な見え方は実機で確認してください。

min_sdk_androidとinsetの指定が結果に効く範囲

min_sdk_android は、生成側が対応の下限を判断するための値です。adaptive iconはAPI 26から入った仕組みなので、ここに26未満を書いた場合でも旧来の正方形アイコンは併せて出力されます。プロジェクトのbuild.gradleに書いたminSdkVersionと食い違わないよう、同じ値を書いておくのが無難でした。なお0.14.3では、設定がない状態でadaptiveやmonochromeのmipmapを作ってしまう挙動が修正されています。古い版で生成した後に設定を削った場合は、res配下に不要なファイルが残っていないかも見てください。

monochromeを指定してテーマ対応アイコンへ載せる条件

Android 13（API 33）から、ユーザーの壁紙に合わせてアイコンの色を揃えるテーマ対応アイコンが入りました。これに乗るにはmonochromeレイヤーという単色版の画像が要ります。flutter_launcher_iconsでは0.14.0の adaptive_icon_monochrome で指定できます。

渡す画像は、白一色のシルエットを透明背景の上に置いた形が扱いやすい構成です。システム側が色を差し替えるため、元画像の色は結果に反映されません。細部の描き込みが多いロゴは単色にすると判別できなくなるので、輪郭だけを残した簡略版を作ってください。

iOS側で審査に落ちない透過処理とiOS 18のダーク・ティント対応

remove_alpha_iosとbackground_color_iosの組み合わせ

App Storeへ提出するアイコンは、透過チャンネルを含められません。ロゴを透明背景のPNGで作っていると、この段階で提出が弾かれます。remove_alpha_ios に true を書くと、生成時に透過を平坦化してくれました。

ただし平坦化した先の色を指定しなければ、意図しない色で埋まる場合があります。background_color_ios に16進のカラーコードを渡し、埋める色を明示してください。ブランドカラーの背景に白抜きロゴを載せる設計なら、ここに背景色を書けば元画像を作り直さずに済みます。

iOS 18のダークアイコンとティントアイコンを用意する条件

iOS 18からは、ホーム画面のダーク表示と、ユーザーが選んだ色で染めるティント表示が加わりました。標準のアイコンだけを渡した場合、システムが自動で変換をかけますが、背景が濃いロゴでは判別しにくい結果になりがちです。

0.14.0で image_path_ios_dark_transparent と image_path_ios_tinted_grayscale が入り、ダーク用とティント用の画像を明示できるようになりました。ダーク用は背景を透明にしたPNG、ティント用は濃淡だけで形が読める階調画像を渡します。カラー画像を自動で灰階調へ落とす desaturate_tinted_to_grayscale_ios もあり、専用画像を作らない場合はこちらで足ります。

この機能を使うなら、0.14.2以降を指定してください。0.14.0と0.14.1では、ダークとティントの出力先ディレクトリが誤っている不具合が残っていました。

14か月更新のない0.14.4を採用してよい条件と代替の見極め

ここからが採否の判断です。使い方の解説記事はいくらでもありますが、更新が止まったツールを業務のプロジェクトへ入れてよいかどうかを扱ったものは多くありません。

依存パッケージとSDK制約から見た現行Flutterでの動作

0.14.4の公開は2025年6月10日で、2026年8月時点でおよそ14か月が経ちました。0.14.3から0.14.4までが約5か月、0.14.0から0.14.3までが約4か月という間隔だったことを踏まえると、明らかに間が空いています。

一方で、動かなくなる兆候は見当たりません。pubspec.yamlのSDK制約はDart 3.0.0以上4.0.0未満と3系の全域を許し、依存も args・image・yaml・path といった枯れたパッケージだけです。Flutter本体のAPIに依存せず、画像を読んで縮小し所定の場所へ書く処理に閉じているため、Flutter側の更新で壊れる面積が小さい作りになっています。pub.dev上の指標はlikes 8,010、pub points 150です。

このパッケージをそのまま採用してよい条件と見送る場面の線引き

採用してよいのは、生成が一度きりの作業として閉じる案件です。リリース前にアイコンを作り、生成物をリポジトリへ入れて以後は触らない使い方なら、ツールが更新されない事実は影響しません。仮に将来動かなくなっても、すでに生成済みのPNGはプロジェクトの中に残ります。

見送りを検討すべきなのは、OS側の新しい表示形式へ継続的に追随する要求がある場合です。Androidのテーマ対応やiOSのティント表示のように、表示の仕組みは数年おきに増えてきました。次の変更が来たときに0.14系のまま止まっていれば、その部分は手作業になります。

icons_launcher 3.1.0へ寄せる判断とその際の書き換え量

代替として現実的なのがicons_launcherです。2026年8月時点の最新は3.1.0で、公開は約4か月前、pub points 160という数値になっています。likesは1.06kとflutter_launcher_iconsの8分の1ほどですが、更新の新しさでは上回りました。

書き換えの手間は小さくありません。icons_launcherは platforms という入れ子の下に各OSを並べ、それぞれ enable の真偽値を持つ構造です。Android側は adaptive_background_color・adaptive_foreground_image・adaptive_monochrome_image、iOS側は dark_path と tinted_path と名前が異なります。設定を丸ごと書き直す前提で見積もってください。

通知アイコンやWebのマスカブルアイコン、ファビコンまで面倒を見る点は、対応範囲を広げたい案件で効きます。逆にAndroidとiOSだけを相手にする案件で移行する動機は薄いのが実情です。Flutter自体を続けるかを含めた判断材料はFlutterの将来性をリリース実績と国内案件数から見た整理にまとめました。

アイコン生成後の確認項目とCIで再生成する場合の運用設計と注意点

アイコン生成物をコミットへ含める運用と毎回再生成する運用の比較

生成されたPNGとContents.jsonをリポジトリへ含めるかどうかは、案件の性質で分かれます。含める運用の利点は再現性です。ツールが将来動かなくなっても、SDKの版が変わっても、リポジトリをクローンすれば同じアイコンでビルドできます。納品後に別のベンダーが引き継ぐ受託案件では、この形が安全でした。

含めない運用は、元画像1枚と設定だけを管理し、ビルドのたびに生成する形です。差分が増えないぶんレビューは軽くなりますが、生成ツールがビルドの必須要素になります。CIの構成を自分たちで維持できる体制があるなら選べる形でした。判断がつかない場合は、含める側を選んでおいてください。

CIで再生成する場合にFlutter SDKの版を固定しておく理由

ビルドのたびに生成する運用を選ぶなら、SDKの版が揺れると生成結果も揺れる前提を持ってください。dart run で走らせる以上、実行環境のDartの版が結果に関わります。開発者の手元とCIで版が違えば、同じ設定から違うファイルが出る余地が残ります。

ここはFVMでFlutter SDKをプロジェクト単位に固定する運用と組み合わせて、CIの実行前に版を揃えるのが確実です。まだ手元の環境が整っていない段階なら、FlutterのSDK導入とflutter doctorによる診断から順に進めてください。

受託案件でアイコンの元データと設定内容を引き継ぐ際の整理方法

納品時に渡すべきものは、生成後のPNGだけではありません。1024pxの元画像、adaptive icon用の前景画像、monochrome用の単色版、iOS 18のダークとティント用の画像、設定ブロックの全文が揃って初めて、次の担当者が同じ結果を再現できます。元データが手元にしか残っていない状態は、担当が変わった時点で作り直しの費用に化けました。

合わせて、なぜその設定にしたかも1行ずつ残してください。min_sdk_androidの値、insetの数値、background_color_iosの色コードは、どれも後から理由が分からなくなりやすい項目です。Flutter / React Nativeによるクロスプラットフォーム開発では、こうした生成物と元データの管理方針まで含めて設計し、引き継ぎ後も同じ手順で再生成できる形で納品しています。

よくある質問

設定を書いて実行してもアイコンが変わらないのはなぜですか？

多くの場合、端末側に古いアイコンが残っているだけです。生成後は一度アプリを削除してから入れ直してください。それでも変わらない場合は、設定ブロックがpubspec.yamlのflutterキーの内側へ入っていないか、image_pathがassetsの実体とずれていないかを確認します。androidに独自の名前を書いたなら、AndroidManifest.xmlのicon属性も対象です。

元画像は何px何形式で用意すればよいですか？

1024x1024pxの正方形PNGが基準です。生成側は縮小しかしないため、これより小さい画像では大きなサイズがぼやけます。adaptive icon用の前景は同じ1024pxで、ロゴを中央のおよそ6割に収め周囲を透明にしたものを別に用意してください。monochrome用は単色のシルエットを渡します。

flutter_iconsとflutter_launcher_iconsのどちらで書けばよいですか？

新規に書くならflutter_launcher_iconsです。0.13.1（2023年4月15日）以降は両方が受け付けられるため、既存プロジェクトのflutter_icons表記をわざわざ書き換える必要はありません。日本語の解説記事は前者の表記が多く残っていますが、公式ドキュメントは後者で統一されています。

Androidのテーマ対応アイコンには必ず対応すべきですか？

Android 16 QPR 2からはmonochromeを持たないアプリのアイコンも自動でテーマ化されるため、対応しなくても表示自体は成立します。ただし自動変換の結果はロゴの形状に左右され、線が細いデザインでは判別しにくくなりました。ブランドの見え方を管理する必要がある案件では、単色版を自前で用意する判断が残ります。

更新が止まっているパッケージを業務で使って問題ありませんか？

生成が一度きりの作業で閉じる案件なら差し支えありません。処理がFlutter本体のAPIに依存せず、画像を縮小して配置する範囲に収まっているため、Flutter側の更新で壊れる面積が小さい作りです。生成物をリポジトリへ含めておけば、将来ツールが動かなくなってもビルドは通ります。OS側の新しい表示形式へ追随し続ける要求がある案件でだけ、icons_launcherへの移行を検討してください。

関連記事

• Flutterの環境構築｜Windows・macOS別のSDK導入とflutter doctor診断：アイコン生成を走らせる前段のSDK導入手順
• FVMとは？Flutter SDKをプロジェクト単位で固定する運用とCI設定：CIで生成結果を揺らさないための版固定
• FlutterGenとは？Flutterのアセット管理を型安全に自動化する使い方・導入手順：元画像を置くassets配下の管理設計
• Freezed（Flutter）とは？データクラスとUnion型の生成と依存の固定：同じくコード生成系ツールの版の扱い方
• Flutterの将来性を数値で判断する｜リリース実績・国内案件数・競合の現在地：Flutter自体を続けるかどうかの判断材料