How to set an Electron app icon on Windows

Electron apps on Windows take their icon from an .ico file.

It shows on the .exe, the taskbar, the Start menu and the installer.

This guide covers making that file from a PNG and wiring it into electron-builder and Electron Forge.

1. Make the .ico from your PNG

Start from a square PNG of at least 256×256 px with a transparent background. Both electron-builder and Electron Forge ask for 256×256 as the minimum.

Upload it to the PNG to ICO converter. The result holds 16, 20, 24, 32, 40, 48, 64, 128 and 256 px in one file, which covers every place Windows shows an app icon.

2. electron-builder

electron-builder looks for icon.ico (or icon.png) in your build resources folder, which is build/ by default. Put the file there and the default Electron icon is replaced automatically.

my-app/
├─ build/
│  └─ icon.ico      ← the converted file
├─ package.json
└─ main.js

To keep the icon somewhere else, point the Windows target at it in your electron-builder configuration:

"build": {
  "win": {
    "icon": "assets/app.ico"
  }
}

A PNG also works with electron-builder, but giving it a finished .ico means you control exactly how the small sizes look.

3. Electron Forge

In Forge, the app icon goes in packagerConfig.icon. You can leave off the extension, and Electron Packager adds the right one for each platform.

// forge.config.js
module.exports = {
  packagerConfig: {
    icon: './assets/app'   // uses app.ico on Windows
  },
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      config: {
        setupIcon: './assets/app.ico'   // icon of Setup.exe
      }
    }
  ]
};

The Squirrel maker's setupIcon is a separate setting. Without it, your app has the right icon but the installer does not.

4. The window icon at runtime

On Windows, the packaged .exe icon is normally what the taskbar shows. You can also pass an icon when creating a window, which matters during development and on Linux:

const win = new BrowserWindow({
  width: 1200,
  height: 800,
  icon: path.join(__dirname, 'assets', 'app.ico')
});

5. Common errors

• Default Electron icon still shows: the file is not in build/, or your config points to a wrong path. Check the build log for icon warnings.
• "Unable to set icon": the .ico is a renamed PNG or is damaged. Convert the PNG properly and rebuild.
• Blurry icon in the taskbar or Explorer: the ICO is missing sizes, so Windows scales another one. A multi-size ICO fixes it.
• Old icon after rebuilding: Windows caches icons by file path. See clearing the icon cache.

Related guides

• Windows icon sizes: which ones an .ico should contain
• Add an icon to a PyInstaller .exe
• ICO not working? Fixes for the most common problems