Toolsets

electron-builder relies on a handful of external binary bundles — the NSIS compiler, Wine, the Windows code-signing tools, the AppImage runtime, FPM, and a few others — that it downloads on demand and caches locally. The top-level toolsets key lets you pin the version of each bundle, or point electron-builder at a bundle you host yourself.

For most projects you never touch this key: every toolset defaults to the newest published bundle. You reach for toolsets only to pin a specific (or legacy) version, or to supply a custom bundle in place of a built-in one.

New in v27

Before v27, toolset selection was a mix of fixed version pins and environment-variable overrides (APPIMAGE_TOOLS_PATH, ELECTRON_BUILDER_NSIS_DIR, USE_SYSTEM_WINE, …). v27 removes every one of those env vars and replaces them with the typed toolsets config on this page. See Toolsets & environment variables in the breaking-changes reference and the Replacing removed environment variables section below.

The toolsets

Each property of toolsets corresponds to one downloadable bundle, hosted at electron-userland/electron-builder-binaries:

Toolset	Used for	`"latest"` resolves to
`winCodeSign`	Windows code signing & resource editing (`signtool` / `osslsigncode`, `rcedit`, Windows Kits for AppX/MSIX)	`1.3.0`
`appimage`	Building `.AppImage` files (`mksquashfs`, `unsquashfs`, the self-executing runtime)	`1.1.0`
`nsis`	Compiling Windows installers (`makensis`, plugin DLLs, `elevate.exe`)	`1.2.1`
`wine`	Running Windows tools (NSIS, rcedit, signtool) on non-Windows hosts	`system` (host `wine` on `PATH`)
`fpm`	Building Linux packages (`.deb`, `.rpm`, `.pacman`, …) on macOS & Linux	`2.2.1`
`linuxToolsMac`	Building Linux targets / `.tar.lz` archives on macOS (`ar`, `lzip`, `gtar`)	`1.0.1`
`sevenZip`	Extracting `.7z` and `.tar.xz` archives internally	`1.0.1`
`icons`	Converting source images to `.icns`, `.ico`, and PNG icon sets	`1.2.3`
`squirrel`	Building Squirrel.Windows installers (`Squirrel.exe`, `SyncReleases.exe`, `nuget.exe`, `7z`) — requires `electron-builder-squirrel-windows`	`1.1.1`

Platform notes

wine is only needed to build Windows targets on a non-Windows machine. On Windows it has no effect. It defaults to the host-installed wine on PATH ("system") on both macOS and Linux, so a macOS host that builds Windows targets needs Wine installed (brew install --cask wine-stable). toolsets.wine: "1.0.1" still downloads the Wine 11.0 bundle on macOS when pinned explicitly, but the published bundle ships no PE builtins, so it cannot run Windows tools on its own.
winCodeSign is used on all platforms (signtool.exe on Windows, osslsigncode on macOS/Linux).
squirrel is only used by the squirrelWindows target. It runs natively on Windows; on macOS/Linux it needs a host-installed mono, and rcedit (from winCodeSign) runs under Wine.
fpm, icons, and squirrel each have only one published version today, so "latest" and the listed version are equivalent.

For the full version-by-version breakdown of what each "latest" bundle upgrades from — and which are drop-in replacements versus behavior changes — see the migration table in Toolset defaults resolve to "latest".

Default resolution — `"latest"`

Every toolsets.* property defaults to "latest". An unset property and the literal string "latest" both resolve to the newest published bundle for that toolset. These two are interchangeable:

{ "build": { "toolsets": {} } }                          // unset → latest
{ "build": { "toolsets": { "nsis": "latest" } } }        // explicit latest

note

null is no longer accepted: it was dropped from the ToolsetConfig type and the configuration schema rejects it, so use "latest" or omit the key. electron-builder migrate-schema removes null entries (and rewrites the retired appimage: "1.0.2" pin to "1.0.3").

Pinning to a concrete version is as simple as naming it:

toolsets:
  nsis: "1.2.1"
  winCodeSign: "1.3.0"

Pinning the legacy bundle (`"0.0.0"`)

Every toolset accepts the sentinel version "0.0.0", which selects the pre-v27 legacy bundle for that tool. It is the escape hatch if a newer bundle introduces a regression:

{
  "build": {
    "toolsets": {
      "winCodeSign": "0.0.0",
      "nsis": "0.0.0",
      "appimage": "0.0.0",
      "wine": "0.0.0"
    }
  }
}

Pinning "0.0.0" also changes a few behaviors that are gated on the bundle version — for example, the legacy AppImage bundle (appimage: "0.0.0") is the FUSE2 runtime and re-adds the automatic --no-sandbox launch argument, and a winCodeSign below 1.3.0 forces the legacy PowerShell path for Azure Trusted Signing (see Code signing & toolsets).

Short-term workaround only

"0.0.0" is intended as a temporary fallback while you resolve an incompatibility. The alias may be removed in a future major release — prefer moving to a current bundle (or a custom toolset) rather than relying on it long-term.

Custom toolsets

Instead of a version string, any toolset can be set to a ToolsetCustom object to supply your own bundle:

toolsets.<name>: { url: string, checksum?: string, version?: string }

Field	Required	Description
`url`	yes	An `https://` URL or a `file://` path. See below.
`checksum`	for downloaded archives	SHA checksum used to verify the bundle. Required for `https://` URLs and for `file://` archive files. Not needed for a bare `file://` directory (used as-is, no caching).
`version`	no	Label used only in the local cache directory name. Falls back to the first 8 characters of `checksum` when omitted.

url accepts two forms:

https://… — the bundle is downloaded, checksum-verified, extracted, and cached locally.
file://… — a local path. A bare directory is used as-is (no checksum, no extraction). A local archive file is extracted and cached (checksum required). Relative file:// paths must resolve inside the project's build-resources directory; absolute paths are used directly.

// Remote bundle (URL) — checksum required
{ "build": { "toolsets": { "nsis": {
  "url": "https://example.com/my-nsis-bundle-1.0.tar.gz",
  "checksum": "sha256:abc123…",
  "version": "my-custom-1.0"
} } } }

// Local directory (used as-is, no checksum)
{ "build": { "toolsets": { "appimage": {
  "url": "file:///path/to/my-appimage-tools-dir"
} } } }

The bundle must mirror the built-in layout

A custom bundle has to match the directory layout of the corresponding built-in bundle — electron-builder looks for the same executables in the same relative paths. Use the build scripts in electron-builder-binaries/packages as the reference for each toolset's expected structure.

Supported archive formats

Archives supplied via url are extracted automatically. Supported formats: .zip, .7z, .tar.gz, .tar.xz. A bare directory (no archive) is used as-is.

sevenZip exception

Because 7-Zip is the tool electron-builder uses to extract .7z and .tar.xz archives, a custom sevenZip bundle can't itself be one of those formats — that would be circular. Supply it only as a .tar.gz, .zip, or bare file:// directory. (The bundle must contain bin/7za on macOS/Linux or bin/7za.exe on Windows.)

Replacing removed environment variables

v27 removes the toolset environment-variable overrides. Replace each with a toolsets.<name> custom object:

Removed env var	Toolset it controlled	Replacement
`APPIMAGE_TOOLS_PATH`	AppImage build tools	`toolsets.appimage: { url }`
`LINUX_TOOLS_MAC_PATH`	linux-tools-mac bundle	`toolsets.linuxToolsMac: { url }`
`CUSTOM_FPM_PATH`	FPM executable	`toolsets.fpm: { url }`
`ELECTRON_BUILDER_NSIS_DIR`	NSIS compiler bundle	`toolsets.nsis: { url }`
`ELECTRON_BUILDER_NSIS_RESOURCES_DIR`	NSIS resources/plugins	`toolsets.nsis: { url }`
`CUSTOM_NSIS_RESOURCES`	Alternate NSIS resources	`toolsets.nsis: { url }`
`ELECTRON_BUILDER_WINE_TOOLSET_DIR`	Wine bundle	`toolsets.wine: { url }`
`USE_SYSTEM_WINE`	Host Wine instead of the bundle	`toolsets.wine: "system"`
`USE_SYSTEM_SIGNCODE`	Host `signtool`/`signcode`	Configure via `win.sign` + `winCodeSign`
`USE_SYSTEM_OSSLSIGNCODE`	Host `osslsigncode`	Configure via `win.sign` + `winCodeSign`
`USE_SYSTEM_FPM`	Host `fpm` instead of the bundle	`toolsets.fpm: { url }`

{ "build": { "toolsets": { "nsis": {
  "url": "https://example.com/my-nsis-bundle.tar.gz",
  "checksum": "sha256:abc123…"
} } } }

No env-var replacement for the signing overrides

The two signing USE_SYSTEM_* variables (USE_SYSTEM_SIGNCODE, USE_SYSTEM_OSSLSIGNCODE) have no env-var equivalent — configure signing through win.sign and the winCodeSign toolset instead. USE_SYSTEM_WINE is replaced by the config value toolsets.wine: "system".

USE_SYSTEM_FPM is likewise removed. On Windows there is no bundled FPM, so an FPM-based target now requires an explicit custom toolsets.fpm ({ url: "file:///path/to/dir" }) and otherwise throws a clear configuration error — previously it silently fell back to a host fpm on PATH.

See Toolset env-var overrides removed for the complete rationale.

Code signing and toolsets

Windows signing is driven by the winCodeSign toolset in combination with win.sign:

The default winCodeSign ("latest" → 1.3.0) bundles a modern signtool / osslsigncode (native arm64) plus the Windows Kits used for AppX/MSIX. The hsm and pkcs11 signing modes require this modern bundle.
Azure Trusted Signing (win.sign: { type: "azure" }) uses the faster signtool /dlib path out of the box, because the default winCodeSign ships the ATS dlib + .NET 8 payload — no pin needed. To force the legacy PowerShell Invoke-TrustedSigning path, pin winCodeSign below 1.3.0 (e.g. "1.2.1" or "0.0.0"). A ToolsetCustom object uses the dlib from your supplied bundle.

For full setup — certificate methods, HSM/PKCS#11, and Azure — see Code Signing for Windows and Azure Trusted Signing signtool /dlib is the default.

The toolsets​

Default resolution — "latest"​

Pinning the legacy bundle ("0.0.0")​

Custom toolsets​

Supported archive formats​

Replacing removed environment variables​

Code signing and toolsets​