msi

The top-level msi key contains a set of options instructing electron-builder on how it should build Windows MSI (Microsoft Installer) packages.

When to Use MSI

MSI packages use Windows Installer technology and are the standard format for enterprise software deployment:

• Group Policy deployment — IT administrators can silently push MSI packages to managed machines via Active Directory
• SCCM / Intune / MDM — Microsoft's enterprise management tools work natively with MSI
• Silent installation — standard /quiet and /passive flags work without custom configuration
• Windows Store compatibility — MSI can be used as a basis for MSIX packaging (see MSI-Wrapped)
• Upgrade/downgrade control — Windows Installer handles version management via upgrade codes

MSI vs. NSIS vs. Portable

Aspect	MSI	NSIS	Portable
Enterprise deployment	Excellent	Limited	None
Silent install	/quiet flag	Custom scripting	N/A
Group Policy	Yes	No	No
Customizability	Moderate (WiX)	Excellent	N/A
UI flexibility	Limited	Highly customizable	N/A
File size	Typically larger	Compressed	No overhead
Auto-update	Not supported via electron-updater	electron-updater	Manual
Recommended for	Enterprise	Consumer	USB/no-install

Upgrade Code

The upgradeCode is a GUID that uniquely identifies your product across all versions. It persists through upgrades and is used by Windows Installer to find and upgrade existing installations.

Critical: Do Not Change After First Release

If you change the upgradeCode after your first release, Windows Installer will treat the new version as a completely different product — existing installations will NOT be upgraded, and users will end up with both versions installed. Set this once and never change it.

msi:
  upgradeCode: "{A1234567-BCDE-F012-3456-789ABCDEF012}"

If not specified, a deterministic GUID is generated from the app ID (appId). Explicitly setting it is strongly recommended for production.

One-Click Installation

msi:
  oneClick: true    # Default: true

When oneClick is true, the installer runs without showing UI (silent install). Set to false for a traditional wizard-style installer.

Per-Machine vs. Per-User Installation

msi:
  perMachine: false   # Default: false (per-user install)

• perMachine: false — installs for the current user only, no admin required
• perMachine: true — installs for all users, requires administrator privileges

For enterprise deployment via Group Policy, perMachine: true is typically required.

Desktop and Start Menu Shortcuts

Shortcut creation is controlled via the inherited CommonWindowsInstallerConfiguration options:

msi:
  createDesktopShortcut: true         # Default: true
  createStartMenuShortcut: true       # Default: true
  menuCategory: "My Company"          # Creates a subfolder in Start Menu
  shortcutName: "My App"             # Overrides default shortcut name
  runAfterFinish: true                # Launch app after installation completes

WiX Customization

The MSI target uses WiX Toolset internally. You can pass additional arguments to the WiX compiler (candle.exe) and linker (light.exe):

msi:
  additionalWixArgs:
    - "-dMyVariable=MyValue"
    - "-ext WixUIExtension"
  additionalLightArgs:
    - "-sice:ICE80"

Use msiProjectCreated hook to modify the generated WiX project files before they are compiled:

msiProjectCreated: ./msi-hook.js

Warnings as Errors

msi:
  warningsAsErrors: true    # Default: true

WiX compiler warnings are treated as errors by default. Set to false if you're using advanced WiX features that trigger known benign warnings.

Silent Installation

MSI packages support standard Windows Installer command-line flags for silent deployment:

# Silent install (no UI)
MyApp-Setup.msi /quiet

# Passive install (progress bar only)
MyApp-Setup.msi /passive

# Silent uninstall
msiexec /x {PRODUCT-CODE} /quiet

# Install per-machine
MyApp-Setup.msi /quiet ALLUSERS=1

# Install to custom path
MyApp-Setup.msi /quiet INSTALLDIR="C:\MyCustomPath\MyApp"

Complete Example

win:
  target:
    - msi

msi:
  oneClick: true
  perMachine: true
  upgradeCode: "{A1234567-BCDE-F012-3456-789ABCDEF012}"
  createDesktopShortcut: true
  createStartMenuShortcut: true
  menuCategory: "My Company"
  runAfterFinish: false       # Don't auto-launch after silent enterprise install
  warningsAsErrors: true

Troubleshooting

Build fails with WiX error: Enable verbose output with DEBUG=electron-builder and check the WiX error codes. Common issues include missing files or invalid GUIDs.

Upgrade installs alongside old version: Verify the upgradeCode is set and has not changed between versions. Also ensure ProductCode (auto-generated per version) is different.

Silent install shows UI: Confirm oneClick: true is set and the /quiet flag is being used. Some antivirus software intercepts installer launches.

Per-machine install fails without admin: Per-machine installation requires elevation. Ensure the deployment mechanism (SCCM, Intune, GPO) runs the installer in a privileged context.

Configuration

Interface: MsiOptions

Extends

• CommonWindowsInstallerConfiguration.TargetSpecificOptions

Properties

additionalLightArgs?

readonly optional additionalLightArgs?: string[] | null

Any additional arguments to be passed to the light.ext, such as ["-cultures:ja-jp"]

---

additionalWixArgs?

readonly optional additionalWixArgs?: string[] | null

Any additional arguments to be passed to the WiX installer compiler, such as ["-ext", "WixUtilExtension"]

---

artifactName?

readonly optional artifactName?: string | null

The artifact file name template.

Inherited from

TargetSpecificOptions.artifactName

---

createDesktopShortcut?

readonly optional createDesktopShortcut?: boolean | "always"

Whether to create desktop shortcut. Set to always if to recreate also on reinstall (even if removed by user).

Default

true

Inherited from

CommonWindowsInstallerConfiguration.createDesktopShortcut

---

createStartMenuShortcut?

readonly optional createStartMenuShortcut?: boolean

Whether to create start menu shortcut.

Default

true

Inherited from

CommonWindowsInstallerConfiguration.createStartMenuShortcut

---

menuCategory?

readonly optional menuCategory?: string | boolean

Whether to create submenu for start menu shortcut and program files directory. If true, company name will be used. Or string value.

Default

false

Inherited from

CommonWindowsInstallerConfiguration.menuCategory

---

oneClick?

readonly optional oneClick?: boolean

One-click installation.

Default

true

Overrides

CommonWindowsInstallerConfiguration.oneClick

---

perMachine?

readonly optional perMachine?: boolean

Whether to install per all users (per-machine).

Default

false

Inherited from

CommonWindowsInstallerConfiguration.perMachine

---

publish?

optional publish?: Publish

Inherited from

TargetSpecificOptions.publish

---

runAfterFinish?

readonly optional runAfterFinish?: boolean

Whether to run the installed application after finish. For assisted installer corresponding checkbox will be removed.

Default

true

Inherited from

CommonWindowsInstallerConfiguration.runAfterFinish

---

shortcutName?

readonly optional shortcutName?: string | null

The name that will be used for all shortcuts. Defaults to the application name.

Inherited from

CommonWindowsInstallerConfiguration.shortcutName

---

upgradeCode?

readonly optional upgradeCode?: string | null

The upgrade code. Optional, by default generated using app id.

---

warningsAsErrors?

readonly optional warningsAsErrors?: boolean

If warningsAsErrors is true (default): treat warnings as errors. If warningsAsErrors is false: allow warnings.

Default

true