A polished desktop application needs a custom icon. It’s a core part of your app’s brand and the first thing users see. By default, Flutter gives you its logo, but changing it is a crucial step before release.
The process is different for each operating system and happens in the native project folders, not in your Dart code. This guide will show you the easy, automated way and the manual, platform-specific methods for Windows, macOS, and Linux.
The Easy Way (Recommended): Using a Package
The most efficient way to set your desktop app icons is with the flutter_launcher_icons package. It’s a popular tool that automates the entire process of generating and placing the correct icon files for all platforms.
Step 1: Add the Package
Add flutter_launcher_icons as a dev dependency in your pubspec.yaml file:
YAML
dev_dependencies:
flutter_launcher_icons: ^0.13.1 # Use the latest version
Step 2: Configure Your Icon
In the same pubspec.yaml file, add a new section to configure the package. You’ll need a high-resolution icon image (e.g., a 1024×1024 PNG) placed in your project, typically in an assets folder.
YAML
flutter_launcher_icons:
# The path to your master icon image
image_path: "assets/icon/app_icon.png"
# Windows specific settings
windows:
generate: true # Enable icon generation for Windows
icon_size: 48 # The size of the icon file
# MacOS specific settings
macos:
generate: true # Enable icon generation for MacOS
# Linux specific settings
linux:
generate: true # Enable icon generation for Linux
Step 3: Run the Package
Save the pubspec.yaml file, and then run the following commands in your terminal:
Bash
# First, get the new package
flutter pub get
# Then, run the package to generate the icons
flutter pub run flutter_launcher_icons
That’s it! The package will automatically create the correctly formatted files (.ico for Windows, .icns for macOS, .png for Linux) and place them in the right directories.
The Manual Method (Platform by Platform)
If you prefer not to use a package or need to troubleshoot, here’s how to change the icons manually for each OS.
🖥️ Windows
- Create an
.icofile: Windows uses a special.icoformat. You cannot just rename a PNG. Use an online tool or a graphics editor to convert your high-resolution PNG icon into an.icofile. - Replace the file: Navigate to the
/windows/runner/resources/directory in your Flutter project. - Replace
app_icon.icowith the new.icofile you created. Ensure it has the exact same name.
🍎 macOS
- Create an
.icnsfile: macOS uses the.icnsformat. Like with Windows, you’ll need to use an online converter or a tool like macOS’s built-iniconutilto create this file from your source PNG. - Navigate to the asset catalog: Go to the
/macos/Runner/Assets.xcassets/AppIcon.appiconset/directory. - Replace the icon files: You can either replace the existing
AppIcon.icnsfile with your own, or replace all the individual PNG files of different sizes within that folder. Replacing the.icnsfile is often simpler.
🐧 Linux
- Prepare a
.pngfile: Linux typically uses standard PNG files for icons. No special conversion is needed. - Navigate to the icons directory: Go to the
/linux/my_application/data/icons/directory. (Themy_applicationfolder name might vary based on your project). - Replace the image: Replace the existing PNG icon file(s) with your own icon, keeping the dimensions and names the same.
✅ Important: Rebuild Your App
After changing the icon using either method, you must perform a full rebuild of your application to see the change. Hot Reload will not work.
Close your app if it’s running, and then execute:
Bash
# Clean the previous build
flutter clean
# Run the app again for your target platform
flutter run -d windows
# or -d macos, or -d linux
Your desktop app should now proudly display its new custom icon!
