Application Icons

Icon requirements and setup for all platforms in electron-builder

Application icons are essential for giving your Electron app a professional appearance across all platforms. electron-builder automatically handles icon generation and conversion for different platforms.

Recommended tools: Icon Composer, AppIcon Generator, MakeAppIcon

Icon File Location

All icon files should be placed in your buildResources directory, which defaults to build/.

my-app/
├── build/
│   ├── icon.icns          # macOS (legacy)
│   ├── icon.icon          # macOS (preferred)
│   ├── icon.ico           # Windows
│   ├── icon.png           # Fallback/Linux source
│   ├── background.png     # macOS DMG background
│   └── [e-mail]  # macOS DMG Retina background
├── src/
└── package.json

macOS Icons

Icon Formats

macOS supports multiple icon formats. electron-builder uses them in the following priority:

1. .icon (preferred) - Apple Icon Composer asset
2. .icns (legacy) - Traditional macOS icon format
3. .png (fallback) - Will be converted to .icns

icon.icon · file

Preferred format for modern macOS

If you set mac.icon to a .icon file, electron-builder compiles it into an asset catalog (Assets.car) and wires it via CFBundleIconName.

Requires Xcode 26+ (actool 26+) on macOS 15+

{
  "build": {
    "mac": {
      "icon": "build/icon.icon"
    }
  }
}

icon.icns · file

Legacy macOS icon format

If you set mac.icon to .icns, it is copied into the app bundle and referenced via CFBundleIconFile.

Minimum size: 512x512 pixels

{
  "build": {
    "mac": {
      "icon": "build/icon.icns"
    }
  }
}

icon.png · file

Universal fallback format

If no .icon or .icns file is provided, electron-builder will use icon.png and convert it to the appropriate format.

Minimum size: 512x512 pixels (1024x1024 recommended)

{
  "build": {
    "mac": {
      "icon": "build/icon.png"
    }
  }
}

DMG Volume Icon

If you only provide .icon format, consider setting dmg.icon explicitly to an .icns file, as the DMG volume icon still requires .icns format.

{
  "build": {
    "mac": {
      "icon": "build/icon.icon"
    },
    "dmg": {
      "icon": "build/icon.icns"
    }
  }
}

DMG Background Images

background.png · file

Background image for macOS DMG installer.

Place in the buildResources directory (defaults to build/).

Recommended size: 540x380 pixels

[e-mail] · file

Retina (HiDPI) background image for macOS DMG installer.

Recommended size: 1080x760 pixels (2x the standard background)

build/
├── background.png      # 540x380
└── [e-mail]   # 1080x760

Example macOS Configuration

{
  "build": {
    "appId": "com.example.app",
    "mac": {
      "icon": "build/icon.icns",
      "category": "public.app-category.productivity"
    },
    "dmg": {
      "icon": "build/icon.icns",
      "background": "build/background.png",
      "window": {
        "width": 540,
        "height": 380
      }
    }
  }
}

Windows Icons

Icon Format

Windows applications use .ico format, which contains multiple icon sizes in a single file.

icon.ico · file

Windows application icon. Should contain multiple sizes: 16x16, 32x32, 48x48, 64x64, 128x128, 256x256.

Minimum size: 256x256 pixels

If not provided, electron-builder will convert icon.png to .ico format.

icon.png · file

If icon.ico is not provided, electron-builder will use icon.png and convert it to .ico.

Minimum size: 256x256 pixels (512x512 recommended)

Icon Configuration

{
  "build": {
    "appId": "com.example.app",
    "win": {
      "icon": "build/icon.ico",
      "target": "nsis"
    }
  }
}

NSIS Installer Icons

You can also customize the NSIS installer icons:

{
  "build": {
    "win": {
      "icon": "build/icon.ico"
    },
    "nsis": {
      "installerIcon": "build/installer-icon.ico",
      "uninstallerIcon": "build/uninstaller-icon.ico",
      "installerHeaderIcon": "build/installer-header-icon.ico"
    }
  }
}

Creating ICO Files

You can create .ico files from .png using various tools:

• ImageMagick:

  convert icon.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico
  

• Online tools: ConvertICO, ICO Convert

Linux Icons

Icon Generation

Linux icon sets are generated automatically based on:

1. The macOS .icns file
2. Or the common icon.png file

electron-builder automatically generates all required Linux icon sizes from your source icon.

Custom Linux Icons

You can provide custom Linux icons by placing them in build/icons/ directory with size-specific filenames:

build/
└── icons/
    ├── 16x16.png
    ├── 32x32.png
    ├── 48x48.png
    ├── 64x64.png
    ├── 128x128.png
    ├── 256x256.png
    └── 512x512.png

Recommended sizes: 16, 32, 48, 64, 128, 256, 512 (or just 512)

Icon Configuration

{
  "build": {
    "appId": "com.example.app",
    "linux": {
      "icon": "build/icons",
      "target": "AppImage"
    }
  }
}

AppImage Icons

For AppImage, you can specify a single icon file:

{
  "build": {
    "linux": {
      "icon": "build/icon.png"
    },
    "appImage": {
      "license": "LICENSE"
    }
  }
}

Windows AppX Icons

Windows AppX (Microsoft Store) requires a specific set of icons and assets. See AppX Assets documentation for detailed requirements.

Required AppX Assets

build/
└── appx/
    ├── StoreLogo.png           # 50x50
    ├── Square44x44Logo.png     # 44x44
    ├── Square150x150Logo.png   # 150x150
    └── Wide310x150Logo.png     # 310x150

Icon Best Practices

Size Requirements Summary

Platform	Format	Minimum Size	Recommended Size
macOS	.icns, .icon, .png	512x512	1024x1024
Windows	.ico, .png	256x256	512x512
Linux	.png	512x512	512x512

Design Guidelines

1. Use vector source - Start with a vector (SVG, AI) for best quality at all sizes
2. Square canvas - Use a square canvas with equal width and height
3. Add padding - Leave ~10% padding around the icon for better appearance
4. Test all sizes - Verify your icon looks good at small sizes (16x16, 32x32)
5. Transparent background - Use transparent backgrounds for PNG sources
6. High resolution - Start with at least 1024x1024 for best results

Common Issues

Icon appears blurry or pixelated

• Source image is too small
• Use higher resolution source (1024x1024 minimum)

Wrong icon appears

• Icon file not in buildResources directory
• Cached icon from previous build
• Try clearing the build directory

DMG icon not showing

• DMG requires .icns format
• If using .icon, set dmg.icon explicitly to .icns

Using a Single PNG Source

For simplicity, you can use a single high-resolution PNG file, and electron-builder will convert it to the appropriate format for each platform:

my-app/
├── build/
│   └── icon.png          # 1024x1024 PNG
└── package.json

{
  "build": {
    "appId": "com.example.app",
    "directories": {
      "buildResources": "build"
    }
  }
}

electron-builder will automatically:

• Convert to .icns for macOS
• Convert to .ico for Windows
• Generate multiple sizes for Linux

Default Icon Behavior

If no icon is provided, the default Electron icon will be used, which is not suitable for production applications.

Icon resolution order:

1. Platform-specific icon (mac.icon, win.icon, linux.icon)
2. icon.icns (macOS), icon.ico (Windows), icon.png (Linux)
3. icon.png (converted to platform format)
4. Default Electron icon (not recommended)

Platform-Specific Icon Configuration

{
  "build": {
    "appId": "com.example.app",
    "mac": {
      "icon": "build/macos-icon.icns"
    },
    "win": {
      "icon": "build/windows-icon.ico"
    },
    "linux": {
      "icon": "build/icons"
    }
  }
}

Advanced Icon Options

Setting Icon to null

You can set icon options to null to explicitly use default behavior:

{
  "build": {
    "dmg": {
      "icon": null  // Use default OS volume icon
    }
  }
}

File Associations Icons

You can specify icons for file associations:

{
  "build": {
    "fileAssociations": [
      {
        "ext": "myfile",
        "name": "My File",
        "icon": "build/file-icon.icns"
      }
    ]
  }
}

Protocol Icons

For macOS protocol schemes:

{
  "build": {
    "protocols": [
      {
        "name": "myapp",
        "schemes": ["myapp"],
        "icon": "build/protocol-icon.icns"
      }
    ]
  }
}

Troubleshooting

Icon not updating

1. Clear the build cache:

   rm -rf dist
   

2. On macOS, clear the icon cache:

   sudo rm -rf /Library/Caches/com.apple.iconservices.store
   killall Finder
   

3. On Windows, rebuild the icon cache:

   ie4uinit.exe -show
   

Verifying Icon Installation

macOS:

# Check app icon
ls -l dist/mac/MyApp.app/Contents/Resources/

# Check Info.plist
defaults read dist/mac/MyApp.app/Contents/Info.plist CFBundleIconFile

Windows:

# Check exe resources
ResourceHacker.exe -open dist/MyApp.exe -action list

Linux:

# Check extracted AppImage
./MyApp.AppImage --appimage-extract
ls squashfs-root/usr/share/icons/

Additional Resources

• macOS Icon Guidelines
• Windows Icon Guidelines
• Linux Icon Theme Specification
• Electron App Icon Documentation