The icons Directory

Every desktop and mobile application needs a set of icon files so the operating system can show the app in the dock, taskbar, launcher, and file manager. Tauri puts all of those files in one place: the icons/ directory inside the Rust backend folder (src-tauri/icons/). This directory is not a loose suggestion — it is the default output location for the tauri icon command and the place where Tauri’s bundler looks for icons unless you override it in tauri.conf.json.

Why a Dedicated Icons Directory Exists

A web application running in a browser needs only a favicon. A native Tauri app, however, runs directly on the user’s operating system, which expects specific icon formats at specific sizes for different UI surfaces. Windows wants an .ico file with multiple embedded layers. macOS needs an .icns file and a set of named PNGs. Linux desktop environments use standalone PNGs of standard sizes. Android and iOS each have their own resolution grids.

Gathering all these files into one well-known directory solves two problems: it gives Tauri’s tooling a predictable place to write generated icons, and it gives developers a single location to manage custom icon sets. The icons/ directory is not a magic folder that automatically works — it must contain files that match what the bundler expects — but it is the place you will return to any time you update your app’s branding.

The Default Icons You Should Replace Immediately

A freshly scaffolded Tauri project includes an icons folder with a default icon set based on the Tauri logo. These default icons look like this:

• icon.png
• icon.icns
• icon.ico
• 32x32.png
• 128x128.png
• 128x128@2x.png

These are not meant for production. Shipping an application with the Tauri logo as its icon makes the app look unfinished and confuses users. The tauri icon command exists precisely to replace them with your own artwork in one step.

Generating Custom Icons with the tauri icon Command

The tauri icon command takes a single source image — a square PNG with transparency or an SVG — and outputs every icon format required for desktop and mobile platforms. It places the desktop icons in the icons/ directory by default and writes mobile icons directly into the platform project folders (Android Studio and Xcode).

Prerequisites

Before running the command, prepare a source image that meets these criteria:

• At least 1024×1024 pixels (larger is better for crisp downscaling)
• PNG with RGBA channels (transparency allowed) or an SVG file
• Square aspect ratio
• The content should have some padding so it doesn’t get clipped when platforms apply rounded corners or masks

Place the file at the project root with the name app-icon.png (the default), or choose any name you prefer.

Running the Command

cd my-tauri-app

npm run tauri icon

npm run tauri icon ./assets/my-icon.png

src-tauri/icons/
├── icon.png
├── icon.icns
├── icon.ico
├── 32x32.png
├── 128x128.png
└── 128x128@2x.png

How the Icons Directory Connects to tauri.conf.json

The Tauri bundler does not blindly grab everything from icons/. Instead, it looks at the bundle.icon array in tauri.conf.json to know exactly which files to include — the same paths Application Icons documents for packaging. After running tauri icon, the default configuration already points to the correct files:

// src-tauri/tauri.conf.json (relevant section)
{
  "bundle": {
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ]
  }
}

The paths are relative to the src-tauri/ directory. If you move your icons to a different location, you must update this array to match.

Manual Icon Creation for Full Control

In some projects, you may want hand-crafted icons at each size instead of relying on automatic resizing. The tauri icon command is a convenience, not a requirement. You can place your own files in the icons/ directory and update bundle.icon to reference them.

Desktop PNGs

PNG icons must meet these requirements:

• Width equals height
• RGBA pixel format (8 bits per channel, 32 bits per pixel)
• Transparent backgrounds are supported

Common sizes for desktop are 32×32, 128×128, 256×256, and 512×512 pixels. The default tauri icon output includes 32x32.png, 128x128.png, and 128x128@2x.png (a 256×256 file named with the @2x convention for high-DPI displays). You can include more sizes, but these three are the minimum that Tauri’s bundler expects by default.

icon.ico for Windows

The .ico format is a container that holds multiple resolutions inside one file. For Windows to display the icon sharply in all contexts — taskbar, Start menu, file explorer, and high-DPI settings — the file must include layers at these pixel sizes:

• 16×16
• 24×24
• 32×32
• 48×48
• 64×64
• 256×256

The 32px layer should be the first layer in the file for optimal display during development.

icon.icns for macOS

The .icns format bundles multiple sizes required by macOS. The official layer sizes and names are defined in the Tauri source repository, but a complete set includes icons at 16×16, 32×32, 128×128, 256×256, and 512×512 pixels, each in both 1x and 2x versions for Retina displays. The tauri icon command produces a valid .icns file automatically; if you create it manually, you can use macOS’s iconutil tool from a properly structured .iconset folder.

Mobile Platform Icons

Mobile platforms have different requirements, and the tauri icon command places their files directly into the native project directories rather than the icons/ folder. Understanding this is important if you ever need to verify or manually replace generated icons.

Android

Android icons are PNGs with the same RGBA requirements as desktop but at different sizes. They go into src-tauri/gen/android/app/src/main/res/ under density-specific folders. The tauri icon command generates the complete grid:

If you need to create these manually — for example, because you want different artwork for adaptive icon layers — Android Studio’s Image Asset Studio is a reliable alternative. Place the resulting PNGs in the corresponding mipmap-* folders.

iOS

iOS icons are PNGs without transparency — the icon must fill the entire square, and the system applies the rounded-corner mask itself. They belong in src-tauri/gen/apple/Assets.xcassets/AppIcon.appiconset/ with file names in the format AppIcon-{size}x{size}@{scale}{extra}.png. Required sizes include:

• 20×20 @1x, @2x, @3x (plus an extra @2x variant for iPad notifications)
• 29×29 @1x, @2x, @3x (plus an extra @2x variant)
• 40×40 @1x, @2x, @3x (plus an extra @2x variant)
• 60×60 @2x, @3x
• 76×76 @1x, @2x
• 83.5×83.5 @2x
• 512×512 @2x (saved as AppIcon-512@2x.png)

Testing Your Icons During Development

During tauri dev, the application uses the same icons that the bundler will pick up — so you will see your custom icon in the dock or taskbar immediately after regenerating. If you change the source image and re-run tauri icon, close and reopen the dev server to see the updated icon. Operating systems cache application icons aggressively; on macOS you may need to run killall Dock or restart the app, and on Windows a system tray icon might persist until you rebuild or clear the icon cache.

Common Mistakes That Produce Generic or Broken Icons

• Using a non-square source image — the command expects a 1:1 aspect ratio. A rectangular image will be stretched, producing a distorted icon.
• Providing a low-resolution PNG — scaling up a 256×256 image to fill a 512×512 layer creates visible blur. Start from at least 1024×1024.
• Forgetting to re-run tauri icon after updating branding — the old generated files stay in icons/ until you regenerate them.
• Modifying icon files in icons/ manually and expecting them to be used on mobile — mobile icons live in gen/, not icons/. The command must be re-run for changes to reach Android and iOS.
• Renaming icon files without updating bundle.icon in the config — the bundler only includes files explicitly listed.

Summary

The icons/ directory is the single point of truth for your Tauri app’s desktop iconography. The tauri icon command turns one source image into every format and size needed across Windows, macOS, Linux, Android, and iOS, populating both icons/ and the native project folders. By keeping a high-resolution source file under version control and regenerating icons as a build step, you avoid manually maintaining dozens of pixel-perfect variants.