> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/electron-userland/electron-builder/llms.txt
> Use this file to discover all available pages before exploring further.

# NSIS Configuration

> Configuration options for NSIS installer in electron-builder

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

These options also applicable for 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 in any case get one installer. Appropriate arch will be installed automatically.
The same applied to web installer (`nsis-web` target).

## Web Installer

To build web installer, set target to `nsis-web`. Web Installer automatically detects OS architecture and downloads corresponding package file. So, user don't need to guess what installer to download and in the same time you don't bundle package files for all architectures in the 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.

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

1. Add file `build/installer.nsh`.
2. Define wanted macro to customise: `customHeader`, `preInit`, `customInit`, `customUnInit`, `customInstall`, `customUnInstall`, `customRemoveFiles`, `customInstallMode`, `customWelcomePage`, `customUnWelcomePage`, `customUnInstallSection`.

<CodeGroup>
  ```nsis Example theme={null}
  !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
  ```
</CodeGroup>

* `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 files).
* `build/x86-unicode` and `build/x86-ansi` are added as `addplugindir`.
* File associations macro `registerFileAssociations` and `unregisterFileAssociations` are still defined.
* All other electron-builder specific flags (e.g. `ONE_CLICK`) are still defined.

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:

```nsis theme={null}
!macro customInstall
  File /oname=$PLUGINSDIR\extramsi.msi "${BUILD_RESOURCES_DIR}\extramsi.msi"
  ExecWait '"msiexec" /i "$PLUGINSDIR\extramsi.msi" /passive'
!macroend
```

<Accordion title="Is there a way to call just when the app is installed (or uninstalled) manually and not on update?">
  Use `${isUpdated}`.

  ```nsis theme={null}
  ${ifNot} ${isUpdated}
    # your code
  ${endIf}
  ```
</Accordion>

## 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](http://stackoverflow.com/a/246935/1910191).
You are not forced to explicitly specify it — name-based [UUID v5](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_5_.28SHA-1_hash_.26_namespace.29) 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 `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.

## Common Questions

<Accordion title="How to change the default installation directory to custom?">
  It is very specific requirement. Do not do if you are not sure. Add custom macro:

  ```nsis theme={null}
  !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
  ```
</Accordion>

<Accordion title="Is it possible to make single installer that will allow configuring user/machine installation?">
  Yes, you need to switch to assisted installer (not default one-click).

  **package.json**

  ```json theme={null}
  "build": {
    "nsis": {
      "oneClick": false
    }
  }
  ```

  **electron-builder.yml**

  ```yaml theme={null}
  nsis:
    oneClick: false
  ```
</Accordion>

## Configuration

<ParamField path="oneClick" type="boolean" default="true">
  Whether to create one-click installer or assisted.
</ParamField>

<ParamField path="perMachine" type="boolean" default="false">
  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.
</ParamField>

<ParamField path="selectPerMachineByDefault" type="boolean" default="false">
  Whether to set per-machine or per-user installation as default selection on the install mode installer page.
</ParamField>

<ParamField path="allowElevation" type="boolean" default="true">
  *Assisted installer only.* Allow requesting for elevation. If false, user will have to restart installer with elevated permissions.
</ParamField>

<ParamField path="allowToChangeInstallationDirectory" type="boolean" default="false">
  *Assisted installer only.* Whether to allow user to change installation directory.
</ParamField>

<ParamField path="removeDefaultUninstallWelcomePage" type="boolean" default="false">
  *Assisted installer only.* Remove the default uninstall welcome page.
</ParamField>

<ParamField path="installerIcon" type="string">
  The path to installer icon, relative to the build resources or to the project directory. Defaults to `build/installerIcon.ico` or application icon.
</ParamField>

<ParamField path="uninstallerIcon" type="string">
  The path to uninstaller icon, relative to the build resources or to the project directory. Defaults to `build/uninstallerIcon.ico` or application icon.
</ParamField>

<ParamField path="installerHeader" type="string" default="build/installerHeader.bmp">
  *Assisted installer only.* `MUI_HEADERIMAGE`, relative to the build resources or to the project directory.
</ParamField>

<ParamField path="installerHeaderIcon" type="string">
  *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.
</ParamField>

<ParamField path="installerSidebar" type="string">
  *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.
</ParamField>

<ParamField path="uninstallerSidebar" type="string">
  *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`
</ParamField>

<ParamField path="uninstallDisplayName" type="string" default="${productName} ${version}">
  The uninstaller display name in the control panel.
</ParamField>

<ParamField path="uninstallUrlHelp" type="string">
  The URL to the uninstaller help page in the control panel. Defaults to homepage from application package.json.
</ParamField>

<ParamField path="uninstallUrlInfoAbout" type="string">
  The URL to the uninstaller info about page in the control panel. Defaults to homepage from application package.json.
</ParamField>

<ParamField path="uninstallUrlUpdateInfo" type="string">
  The URL to the uninstaller update info page in the control panel. Defaults to homepage from application package.json.
</ParamField>

<ParamField path="uninstallUrlReadme" type="string">
  The URL to the uninstaller readme page in the control panel. Defaults to homepage from application package.json.
</ParamField>

<ParamField path="include" type="string">
  The path to NSIS include script to customize installer. Defaults to `build/installer.nsh`. See [Custom NSIS script](#custom-nsis-script).
</ParamField>

<ParamField path="script" type="string">
  The path to NSIS script to customize installer. Defaults to `build/installer.nsi`. See [Custom NSIS script](#custom-nsis-script).
</ParamField>

<ParamField path="license" type="string">
  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.

  Appropriate license file will be selected by user OS language.
</ParamField>

<ParamField path="artifactName" type="string" default="${productName} Setup ${version}.${ext}">
  The artifact file name template.
</ParamField>

<ParamField path="deleteAppDataOnUninstall" type="boolean" default="false">
  *One-click installer only.* Whether to delete app data on uninstall.
</ParamField>

<ParamField path="displayLanguageSelector" type="boolean" default="false">
  Whether to display a language selection dialog. Not recommended (by default will be detected using OS language).
</ParamField>

<ParamField path="installerLanguages" type="string | string[]">
  The installer languages (e.g. `en_US`, `de_DE`). Change only if you understand what do you do and for what.
</ParamField>

<ParamField path="language" type="string" default="1033">
  LCID Dec, defaults to `1033` (English - United States).
</ParamField>

<ParamField path="multiLanguageInstaller" type="boolean">
  Whether to create multi-language installer. Defaults to `unicode` option value.
</ParamField>

<ParamField path="packElevateHelper" type="boolean" default="true">
  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`.
</ParamField>

<ParamField path="preCompressedFileExtensions" type="string | string[]" default="[&#x22;.avi&#x22;, &#x22;.mov&#x22;, &#x22;.m4v&#x22;, &#x22;.mp4&#x22;, &#x22;.m4p&#x22;, &#x22;.qt&#x22;, &#x22;.mkv&#x22;, &#x22;.webm&#x22;, &#x22;.vmdk&#x22;]">
  The file extension of files that will be not compressed. Applicable only for `extraResources` and `extraFiles` files.
</ParamField>

<ParamField path="buildUniversalInstaller" type="boolean" default="true">
  Disable building an universal installer of the archs specified in the target configuration. *Not supported for nsis-web*
</ParamField>

<ParamField path="unicode" type="boolean" default="true">
  Whether to create Unicode installer.
</ParamField>

<ParamField path="guid" type="string">
  See [GUID vs Application Name](#guid-vs-application-name).
</ParamField>

<ParamField path="warningsAsErrors" type="boolean" default="true">
  If `warningsAsErrors` is `true` (default): NSIS will treat warnings as errors. If `warningsAsErrors` is `false`: NSIS will allow warnings.
</ParamField>

<ParamField path="customNsisBinary" type="CustomNsisBinary">
  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`)
</ParamField>

<ParamField path="customNsisResources" type="CustomNsisResources">
  Allows you to provide your own `nsis-resources`.
</ParamField>

### Common Installer Options

<ParamField path="runAfterFinish" type="boolean" default="true">
  Whether to run the installed application after finish. For assisted installer corresponding checkbox will be removed.
</ParamField>

<ParamField path="createDesktopShortcut" type="boolean | 'always'" default="true">
  Whether to create desktop shortcut. Set to `always` if to recreate also on reinstall (even if removed by user).
</ParamField>

<ParamField path="createStartMenuShortcut" type="boolean" default="true">
  Whether to create start menu shortcut.
</ParamField>

<ParamField path="menuCategory" type="boolean | string" default="false">
  Whether to create submenu for start menu shortcut and program files directory. If `true`, company name will be used. Or string value.
</ParamField>

<ParamField path="shortcutName" type="string">
  The name that will be used for all shortcuts. Defaults to the application name.
</ParamField>

## Web Installer Configuration

Use the `nsisWeb` key for web installer specific options.

<ParamField path="appPackageUrl" type="string">
  The application package download URL. Optional — by default computed using publish configuration.

  URL like `https://example.com/download/latest` allows web installer to be version independent (installer will download latest application package). Please note — it is full URL.

  Custom `X-Arch` http header is set to `32` or `64`.
</ParamField>

<ParamField path="artifactName" type="string" default="${productName} Web Setup ${version}.${ext}">
  The artifact file name template for web installer.
</ParamField>

## Portable Options

Use the `portable` target for portable app options.

<ParamField path="requestExecutionLevel" type="'user' | 'highest' | 'admin'" default="user">
  The requested execution level for Windows.
</ParamField>

<ParamField path="unpackDirName" type="string | boolean">
  The unpack directory for the portable app resources.

  If set to a string, it will be the name in TEMP directory. If set explicitly to `false`, it will use the Windows temp directory (\$PLUGINSDIR) that is unique to each launch of the portable application.

  Defaults to uuid of build (changed on each build of portable executable).
</ParamField>

<ParamField path="splashImage" type="string">
  The image to show while the portable executable is extracting. This image must be a bitmap (`.bmp`) image.
</ParamField>