Application Icons
How to generate, configure, and customise the application icons that identify your Tauri v2 app on desktop and mobile platforms
Application icons are the images that operating systems display for your app — in the taskbar, dock, desktop shortcuts, system tray, and app store listings. Tauri v2 provides a command-line tool that turns a single source image into every icon format needed across all supported platforms, and a configuration field that tells the bundler which files to use. The generated files typically land in the src-tauri/icons directory.
The tauri icon Command
The fastest way to produce a full set of application icons is the built‑in tauri icon command. It reads one source file (a square PNG or SVG with transparency), resizes it to the required dimensions, and writes the output to the correct locations.
Step 1: Prepare your source icon
Start with a high‑resolution square image — 1024×1024 pixels is ideal. The file can be PNG or SVG and should include a transparent background if your app icon uses transparency. Rounded corners, drop shadows, or platform‑specific styling will be handled by the operating system, so you only need a clean, centered design.
Step 2: Run the icon generation command
Open a terminal in your project root (where package.json lives) and run:
npm run tauri icon ./app-icon.png
If you use a different package manager, replace npm run with pnpm, yarn, bun, or cargo. The argument ./app-icon.png is the path to your source file; the command defaults to ./app-icon.png when no path is given.
The command places desktop icons in src-tauri/icons by default and automatically injects mobile icons into the Xcode and Android Studio project directories (src-tauri/gen/apple/Assets.xcassets/… and src-tauri/gen/android/app/src/main/res/…).
Custom output directory:
You can change where desktop icons are written with --output <path>. The path is relative to the location of tauri.conf.json.
Step 3: Verify the generated icons
After the command finishes, check that the following files exist inside src-tauri/icons (the defaults):
32x32.png128x128.png128x128@2x.pngicon.icnsicon.icoicon.png(a 512×512 copy used internally)
For mobile targets you should also see new icon files under src-tauri/gen/android/app/src/main/res/mipmap-* and src-tauri/gen/apple/Assets.xcassets/AppIcon.appiconset.
Icons generated successfully:
If you see all the files listed above, your icons are ready. The bundler will automatically include them in the final application package — no manual copy step required.
Never ship with the default Tauri logo:
Tauri ships with its own icon set so that a new project runs immediately. These default icons should be replaced before you distribute your app. Running tauri icon is a required step in every release workflow.
Command options
The tauri icon command supports a few useful flags:
| Option | Description |
|---|---|
--output <path> | Destination directory for desktop icons (default: icons next to tauri.conf.json). |
--png <sizes> | Custom PNG sizes to generate, e.g. --png 16,24,64. When set, the default sizes are not generated. |
--ios-color <color> | Background colour for the iOS icon, expressed as a CSS colour string. Defaults to #fff. |
--verbose | Print extra information during generation. |
If you need only a subset of PNG sizes, --png lets you override the defaults. The desktop formats .icns and .ico are still generated automatically because they are required by macOS and Windows respectively.
Configuring icons in tauri.conf.json
Even though tauri icon places files in the expected location, you must still declare them in the Tauri configuration so the bundler knows which files to include. The relevant field is bundle > icon — an array of relative paths.
Open src-tauri/tauri.conf.json and make sure the bundle section looks similar to this:
{
"bundle": {
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
]
}
}
Each entry is a path relative to the src-tauri directory. The order does not matter; the bundler picks the appropriate format per target platform.
What each icon is used for
32x32.png— Taskbar icon on Windows, small size in file explorers.128x128.png— Default app icon size on many Linux desktops.128x128@2x.png— High‑DPI (Retina) variant on macOS and some Linux environments.icon.ico— Windows.exeand shortcut icon. Must contain multiple resolutions inside a single file (the command handles this).icon.icns— macOS.appbundle icon. Also a container with multiple sizes.
Paths must match generated files:
If you move the generated icons to a different folder or rename them, update the paths in the icon array accordingly. Missing files will cause the bundler to fall back to Tauri’s default logo — silently.
Manual icon creation
Using tauri icon is almost always the best choice, but you might want hand‑crafted icons with different designs at different sizes, or you might be working in an environment where the CLI’s image resizing is not acceptable. This section covers the exact specifications for each format when you create icons manually.
Desktop icon formats
PNG requirements:
- Square (width equals height)
- RGBA colour with transparency
- 32 bits per pixel (8 bits per channel)
- Common sizes: 32×32, 128×128, 256×256, and 512×512 pixels
ICO (Windows):
- The file must contain layers for 16, 24, 32, 48, 64, and 256 pixels.
- For development builds, the 32‑pixel layer should be the first layer in the file for the best display.
ICNS (macOS):
- The file must contain specific layer sizes; the required list is maintained in the Tauri repository.
If you create your own .png files, you still need to list them in the bundle.icon array — the same way as the auto‑generated ones.
Mobile icons
Mobile platforms need additional icon sets that are placed directly inside the platform project directories, not inside src-tauri/icons. The tauri icon command handles this automatically. When you must create them by hand, follow the specifications below.
Android icons are PNG files placed inside the mipmap density folders under src-tauri/gen/android/app/src/main/res/. The following files are expected in each density bucket:
| Density | Folder | ic_launcher.png | ic_launcher_round.png | ic_launcher_foreground.png |
|---|---|---|---|---|
| mdpi | mipmap-mdpi | 48×48 | 48×48 | 108×108 |
| hdpi | mipmap-hdpi | 72×72 | 72×72 | 162×162 |
| xhdpi | mipmap-xhdpi | 96×96 | 96×96 | 216×216 |
| xxhdpi | mipmap-xxhdpi | 144×144 | 144×144 | 324×324 |
| xxxhdpi | mipmap-xxxhdpi | 192×192 | 192×192 | 432×432 |
Android uses adaptive icons, which separate the foreground artwork (ic_launcher_foreground.png) from the background layer. The standard launcher icons (ic_launcher.png and ic_launcher_round.png) are fallbacks for older devices. All icons must follow the same PNG requirements as desktop icons (square, RGBA, 32bpp).
Adaptive icon background:
The background for adaptive icons is defined in XML (ic_launcher.xml in the res/mipmap-anydpi-v26 folder). You can change its colour there without touching the PNG files.
Common mistakes and how to avoid them
Forgetting the bundle.icon array:
After generating icons, you must declare them in tauri.conf.json under bundle.icon. If this array is empty or missing, the bundler will not include your custom icons. The resulting app will display Tauri’s default logo.
Transparency on iOS:
iOS icons cannot have transparency. If your source image is a PNG with a transparent background, the iOS icon will appear with black artefacts or a broken silhouette. Use the --ios-color flag to set a solid background, or create a separate icon without transparency for iOS.
Wrong ico layer order:
If you create a .ico file manually, place the 32‑pixel layer first inside the container. Tauri’s development‑mode window title bar uses this first layer; a different order can cause a blurry or missing icon while you’re building and testing.
Verifying icons before release:
You can test your icons by building a debug bundle (npm run tauri build -- --debug) and installing it on your target OS. Check the taskbar, dock, and system tray (if applicable) to confirm the icon appears correctly at all sizes.
Summary
Application icons are one of the first things a user notices. Tauri v2 removes the manual drudgery with tauri icon, which produces every required format from a single source file. The only configuration you need to manage is the bundle.icon array in tauri.conf.json — point it at the generated files and your app will carry the right identity on every platform. If you need full control over the design, the manual creation specifications give you an exact recipe for each target.