Skip to main content

NSIS

The top-level nsis key contains a set of options instructing electron-builder on how it should build NSIS target (default target for Windows).

These options are also applicable for the Web installer, use top-level nsisWeb key.

Unicode enabled by default. Large strings are supported (maximum string length of 8192 bytes instead of the default of 1024 bytes).

32 bit + 64 bit​

If you build both ia32 and x64 arch (--x64 --ia32), you will always get one installer. The appropriate arch will be installed automatically. The same applied to web installer (nsis-web target). The same dual-arch installer mechanism also applies to --x64 --arm64.

ia32 requires Electron <= 43

Electron 44 removed Windows ia32 builds — building ia32 requires electronVersion <= 43.x (supported until the v43 series reaches end-of-life in January 2027).

Web Installer​

To build web installer, set target to nsis-web. Web Installer automatically detects OS architecture and downloads corresponding package file. So, the user doesn't need to guess what installer to download and at the same time you don't bundle package files for all architectures in one installer (as in case of default nsis target). It doesn't matter for common Electron application (due to superb LZMA compression, size difference is acceptable), but if your application is huge, Web Installer is a solution.

To customize web installer, use the top-level nsisWeb key (not nsis).

If for some reasons web installer cannot download (antivirus, offline):

  • Download package file into the same directory where installer located. It will be detected automatically and used instead of downloading from the Internet. Please note — only original package file is allowed (checksum is checked).
  • Specify any local package file using --package-file=path_to_file.

Custom NSIS script​

Two options are available — include and script. script allows you to provide completely different NSIS script. For most cases it is not required as you need only to customise some aspects, but still use well-tested and maintained default NSIS script. So, include is recommended.

warning
Custom script disables built-in safeguards

When you provide a custom script, electron-builder no longer generates (and signs) the uninstaller for you and skips installer size verification. Prefer include unless you really need to replace the whole script.

Keep in mind — if you customize the NSIS script, you should always mention it in issue reports. And don't expect that your issue will be resolved.

v27: file-association ProgID format changed

NSIS installers now register each fileAssociations entry under a unique generated ProgID (<program>.<component>, derived from productName + the app GUID) instead of using the association name/extension verbatim, which could collide with unrelated apps. fileAssociations and its name/ext/description fields are unchanged and nothing needs migrating — but if your custom include/script (or external tooling) hard-codes the old ProgID (the association name or extension) to add shell verbs or registry keys, update it to the new generated value. See v27 Breaking Changes → NSIS file-association ProgID.

  1. Add file build/installer.nsh (or set include explicitly — a single path, or an array of paths that are all included in order, e.g. "include": ["build/installer.nsh", "build/signing.nsh"]; each path is resolved relative to the build resources directory first, then relative to the project directory).
  2. Define wanted macro to customise: customHeader, preInit, customInit, customUnInit, customInstall, customUnInstall, customRemoveFiles, customInstallMode, customWelcomePage, customUnWelcomePage, customUnInstallSection.
Example
!macro customHeader
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customHeader"
!macroend

!macro preInit
  ; This macro is inserted at the beginning of the NSIS .OnInit callback
  !system "echo '' > ${BUILD_RESOURCES_DIR}/preInit"
!macroend

!macro customInit
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customInit"
!macroend

!macro customInstall
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customInstall"
!macroend

!macro customInstallMode
  # set $isForceMachineInstall or $isForceCurrentInstall
  # to enforce one or the other modes.
!macroend

!macro customWelcomePage
  # Welcome Page is not added by default for installer.
  !insertMacro MUI_PAGE_WELCOME
!macroend

!macro customUnWelcomePage
  !define MUI_WELCOMEPAGE_TITLE "custom title for uninstaller welcome page"
  !define MUI_WELCOMEPAGE_TEXT "custom text for uninstaller welcome page $\r$\n more"
  !insertmacro MUI_UNPAGE_WELCOME
!macroend

!macro customUnInstallSection
  Section /o "un.Some cool checkbox"
    ; You can add some uninstall section as component page
    ; If defined, then always run after `customUnInstall`
  SectionEnd
!macroend
  • BUILD_RESOURCES_DIR and PROJECT_DIR are defined.
  • build is added as addincludedir (i.e. you don't need to use BUILD_RESOURCES_DIR to !include sibling files from the build resources directory).
  • build/x86-unicode and build/x86-ansi are added as addplugindir (each one only when the directory exists, regardless of the unicode option).
  • File associations macro registerFileAssociations and unregisterFileAssociations are still defined.
  • All other electron-builder specific flags (e.g. ONE_CLICK) are still defined.
note
Uninstaller lifecycle — customUnInstall changes take effect one version later

The uninstaller that runs during an uninstall or during an update is the Uninstall <app>.exe that was written to disk by the previously installed version — not the one embedded in the installer that is currently running. So when you add or change customUnInstall (or anything else affecting the uninstaller), the change only becomes active after the next install: version N ships the new uninstaller, and it is first executed when version N is uninstalled or updated to N+1. If your customUnInstall "does not fire", it is almost always because the machine still runs the old uninstaller from the previous version.

warning
Uninstall registry key — do not hard-code ...\Uninstall\<appId>

electron-builder registers the uninstall entry under Software\Microsoft\Windows\CurrentVersion\Uninstall\${UNINSTALL_APP_KEY}, where UNINSTALL_APP_KEY is the application GUID (with each \ replaced by " - ", i.e. space, hyphen, space) — not the appId. In a custom script use the provided defines instead of building the path yourself: ${UNINSTALL_REGISTRY_KEY} (the full key, see multiUser.nsh) or ${UNINSTALL_APP_KEY}. A hard-coded Software\Microsoft\Windows\CurrentVersion\Uninstall\${APP_ID} points at a key electron-builder never writes.

If you want to include additional resources for use during installation, such as scripts or additional installers, you can place them in the build directory and include them with File. For example, to include and run extramsi.msi during installation, place it in the build directory and use the following:

!macro customInstall
  File /oname=$PLUGINSDIR\extramsi.msi "${BUILD_RESOURCES_DIR}\extramsi.msi"
  ExecWait '"msiexec" /i "$PLUGINSDIR\extramsi.msi" /passive'
!macroend
Is there a way to call just when the app is installed (or uninstalled) manually and not on update?

Use ${isUpdated}.

${ifNot} ${isUpdated}
  # your code
${endIf}

GUID vs Application Name​

Windows requires to use registry keys (e.g. INSTALL/UNINSTALL info). Squirrel.Windows simply uses application name as key. But it is not robust — Google can use key Google Chrome SxS, because it is a Google.

So, it is better to use GUID. You are not forced to explicitly specify it — name-based UUID v5 will be generated from your appId or name. It means that you should not change appId once your application in use (or name if appId was not set). Application product name (title) or description can be safely changed.

You can explicitly set guid using option nsis.guid, but it is not recommended — consider using appId.

It is also important to set the Application User Model ID (AUMID) to the appId of the application, in order for notifications on Windows 8/8.1 to function and for Window 10 notifications to display the app icon within the notifications by default. The AUMID should be set within the Main process and before any BrowserWindows have been opened, it is normally the first piece of code executed: app.setAppUserModelId(appId)

Portable​

To build portable app, set target to portable (or pass --win portable).

For portable app, following environment variables are available:

  • PORTABLE_EXECUTABLE_FILE - path to the portable executable.
  • PORTABLE_EXECUTABLE_DIR - directory where the portable executable is located.
  • PORTABLE_EXECUTABLE_APP_FILENAME - sanitized app name to use in file paths.

The portable target also supports a custom NSIS script via portable.include (a single path or an array of paths). Unlike the installer targets, build/installer.nsh is not auto-discovered for portable builds — a custom script is only included when the option is explicitly set, so an installer.nsh written for the installer target does not silently leak into portable builds.

Common Questions​

How do I change the default installation directory?

It is very specific requirement. Do not do if you are not sure. Add custom macro:

!macro preInit
  SetRegView 64
  WriteRegExpandStr HKLM "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  WriteRegExpandStr HKCU "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  SetRegView 32
  WriteRegExpandStr HKLM "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  WriteRegExpandStr HKCU "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
!macroend
Is it possible to make a single installer that will allow configuring user/machine installation?

Yes, you need to switch to assisted installer (not default one-click).

package.json

"build": {
  "nsis": {
    "oneClick": false
  }
}

electron-builder.yml

nsis:
  oneClick: false

Configuration​

Interface: NsisOptions

Extends​

Extended by​

Properties​

allowElevation?​

readonly optional allowElevation?: boolean

assisted installer only. Allow requesting for elevation. If false, user will have to restart installer with elevated permissions.

Default​

true

allowToChangeInstallationDirectory?​

readonly optional allowToChangeInstallationDirectory?: boolean

assisted installer only. Whether to allow user to change installation directory.

Default​

false

artifactName?​

readonly optional artifactName?: string | null

The artifact file name template. Defaults to ${productName} Setup ${version}.${ext}.

Overrides​

TargetSpecificOptions.artifactName

buildUniversalInstaller?​

readonly optional buildUniversalInstaller?: boolean

Disable building an universal installer of the archs specified in the target configuration Not supported for nsis-web

Default​

true

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

customNsisBinary?​

readonly optional customNsisBinary?: CustomNsisBinary | null

Allows you to provide your own makensis, such as one with support for debug logging via LogSet and LogText. (Logging also requires option debugLogging = true)

Inherited from​

CommonNsisOptions.customNsisBinary

customNsisResources?​

readonly optional customNsisResources?: CustomNsisResources | null

Allows you to provide your own nsis-resources

Inherited from​

CommonNsisOptions.customNsisResources

deleteAppDataOnUninstall?​

readonly optional deleteAppDataOnUninstall?: boolean

one-click installer only. Whether to delete app data on uninstall.

Default​

false

differentialPackage?​

readonly optional differentialPackage?: boolean | "compressed" | "store-asar"

Marks the package as built with differential download support for the update server, and selects how the app package is compressed:

  • false — no differential download support.
  • "store-asar" — differential-aware, with the app's resources/app.asar stored uncompressed (7-Zip Copy) inside the package. The differential updater diffs the compressed package with a content-defined blockmap, and the asar is a single compressed member — so any change to app code re-downloads the entire compressed asar (~100% of the member; its header rewrite alone diverges every block). Storing it keeps unchanged regions byte-identical between releases, making the delta proportional to what actually changed (measured on a ~32 MB asar: a one-line source change cost 0.2% instead of 100%). Trade-off: the installer and full package grow by roughly what compressing the asar saved.
  • anything else (true, "compressed", unset) — differential-aware, whole package compressed.

Default​

true

displayLanguageSelector?​

readonly optional displayLanguageSelector?: boolean

Whether to display a language selection dialog. Not recommended (by default will be detected using OS language).

Default​

false

guid?​

readonly optional guid?: string | null

The GUID for the installer. Used to identify the application for upgrade and uninstall operations. If not specified, a deterministic GUID is generated from the app ID (appId) — but this means changing your appId will break silent upgrades of existing installs.

See​

GUID vs Application Name

Inherited from​

CommonNsisOptions.guid

include?​

readonly optional include?: string | string[] | null

The path to NSIS include script to customize installer, or an array of such paths to include multiple scripts. Defaults to build/installer.nsh. See Custom NSIS script.

Each path is resolved relative to the build resources directory first and then relative to the project directory. When an array is provided, all scripts are included in the specified order.

installerHeader?​

readonly optional installerHeader?: string | null

assisted installer only. MUI_HEADERIMAGE, relative to the build resources or to the project directory.

Default​

build/installerHeader.bmp

installerHeaderIcon?​

readonly optional installerHeaderIcon?: string | null

one-click installer only. The path to header icon (above the progress bar), relative to the build resources or to the project directory. Defaults to build/installerHeaderIcon.ico or application icon.

installerIcon?​

readonly optional installerIcon?: string | null

The path to installer icon, relative to the build resources or to the project directory. Defaults to build/installerIcon.ico or application icon.

installerLanguages?​

readonly optional installerLanguages?: string | string[] | null

The installer languages (e.g. en_US, de_DE). Change only if you understand what do you do and for what.

installerSidebar?​

readonly optional installerSidebar?: string | null

assisted installer only. MUI_WELCOMEFINISHPAGE_BITMAP, relative to the build resources or to the project directory. Defaults to build/installerSidebar.bmp or ${NSISDIR}\\Contrib\\Graphics\\Wizard\\nsis3-metro.bmp. Image size 164 × 314 pixels.

language?​

readonly optional language?: string | null

LCID Dec, defaults to 1033(English - United States).

license?​

readonly optional license?: string | null

The path to EULA license file. Defaults to license.txt or eula.txt (or uppercase variants). In addition to txt, rtf and html supported (don't forget to use target="_blank" for links).

Multiple license files in different languages are supported — use lang postfix (e.g. _de, _ru). For example, create files license_de.txt and license_en.txt in the build resources. If OS language is german, license_de.txt will be displayed. See map of language code to name.

Appropriate license file will be selected by user OS language.

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

multiLanguageInstaller?​

readonly optional multiLanguageInstaller?: boolean

Whether to create multi-language installer. Defaults to unicode option value.

oneClick?​

readonly optional oneClick?: boolean

Whether to create one-click installer or assisted.

Default​

true

Overrides​

CommonWindowsInstallerConfiguration.oneClick

packElevateHelper?​

readonly optional packElevateHelper?: boolean

Whether to pack the elevate executable (required for electron-updater if per-machine installer used or can be used in the future). Ignored if perMachine is set to true.

Default​

true

perMachine?​

readonly optional perMachine?: boolean

Whether to show install mode installer page (choice per-machine or per-user) for assisted installer. Or whether installation always per all users (per-machine).

If oneClick is true (default): Whether to install per all users (per-machine).

If oneClick is false and perMachine is true: no install mode installer page, always install per-machine.

If oneClick is false and perMachine is false (default): install mode installer page.

Default​

false

Overrides​

CommonWindowsInstallerConfiguration.perMachine

preCompressedFileExtensions?​

readonly optional preCompressedFileExtensions?: string | string[] | null

The file extension of files that will be not compressed. Applicable only for extraResources and extraFiles files.

Default​

[".avi", ".mov", ".m4v", ".mp4", ".m4p", ".qt", ".mkv", ".webm", ".vmdk"]

publish?​

optional publish?: Publish

Inherited from​

TargetSpecificOptions.publish

removeDefaultUninstallWelcomePage?​

readonly optional removeDefaultUninstallWelcomePage?: boolean

assisted installer only. remove the default uninstall welcome page.

Default​

false

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

script?​

readonly optional script?: string | null

The path to NSIS script to customize installer. Defaults to build/installer.nsi. See Custom NSIS script.

selectPerMachineByDefault?​

readonly optional selectPerMachineByDefault?: boolean

Whether to set per-machine or per-user installation as default selection on the install mode installer page.

Default​

false

shortcutName?​

readonly optional shortcutName?: string | null

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

Inherited from​

CommonWindowsInstallerConfiguration.shortcutName

unicode?​

readonly optional unicode?: boolean

Whether to create Unicode installer.

Default​

true

Inherited from​

CommonNsisOptions.unicode

uninstallDisplayName?​

readonly optional uninstallDisplayName?: string | null

The uninstaller display name in the control panel.

Default​

${productName} ${version}

uninstallerIcon?​

readonly optional uninstallerIcon?: string | null

The path to uninstaller icon, relative to the build resources or to the project directory. Defaults to build/uninstallerIcon.ico or application icon.

uninstallerSidebar?​

readonly optional uninstallerSidebar?: string | null

assisted installer only. MUI_UNWELCOMEFINISHPAGE_BITMAP, relative to the build resources or to the project directory. Defaults to installerSidebar option or build/uninstallerSidebar.bmp or build/installerSidebar.bmp or ${NSISDIR}\\Contrib\\Graphics\\Wizard\\nsis3-metro.bmp

uninstallUrlHelp?​

readonly optional uninstallUrlHelp?: string | null

The URL to the uninstaller help page in the control panel. Defaults to homepage from application package.json.

uninstallUrlInfoAbout?​

readonly optional uninstallUrlInfoAbout?: string | null

The URL to the uninstaller info about page in the control panel. Defaults to homepage from application package.json.

uninstallUrlReadme?​

readonly optional uninstallUrlReadme?: string | null

The URL to the uninstaller readme page in the control panel. Defaults to homepage from application package.json.

uninstallUrlUpdateInfo?​

readonly optional uninstallUrlUpdateInfo?: string | null

The URL to the uninstaller update info page in the control panel. Defaults to homepage from application package.json.

useZip?​

readonly optional useZip?: boolean

Forces zip compression format instead of LZMA. Used internally for differential update packages.

Default​

false

Inherited from​

CommonNsisOptions.useZip

warningsAsErrors?​

readonly optional warningsAsErrors?: boolean

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

Default​

true

Inherited from​

CommonNsisOptions.warningsAsErrors