electron-builder Documentation

Technical Documentation: electron-userland/electron-builder

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

electron-builder [](https://www.npmjs.com/package/electron-builder) [](https://yarn.pm/electron-builder)

A complete solution to package and build a ready for distribution Electron app for macOS, Windows and Linux with “auto update” support out of the box. 📦

Always looking for community contributions! 👀 Setting up a dev environment is easy to do 🪩

Sponsors Copy Chapter

Documentation Copy Chapter

See the full documentation on electron.build.

• NPM packages management:
  • Native application dependencies compilation (including Yarn support).
  • Development dependencies are never included. You don't need to ignore them explicitly.
  • Two package.json structure is supported, but you are not forced to use it even if you have native production dependencies.
• Code Signing on a CI server or development machine.
• Auto Update ready application packaging.
• Numerous target formats:
  • All platforms: 7z, zip, tar.xz, tar.7z, tar.lz, tar.gz, tar.bz2, dir (unpacked directory).
  • macOS: dmg, pkg, mas.
  • Linux: AppImage, snap, debian package (deb), rpm, freebsd, pacman, p5p, apk.
  • Windows: nsis (Installer), nsis-web (Web installer), portable (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows.
• Publishing artifacts to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.
• Advanced building:
  • Pack in a distributable format (already packaged app).
  • Separate build steps.
  • Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage.
• Docker images to build Electron app for Linux or Windows on any platform.
• Downloads all required tool files on demand automatically (e.g., to code sign a Windows application, to make AppX), no setup required.

Requirements Copy Chapter

Node.js >=22.12.0 is required for v27.

⚠️ Upgrading from v26? v27 is a major release with breaking changes (native ESM, Node >=22.12, and removed deprecated APIs). Start with What's New in v27 for the highlights and the silent default changes, then read the full breaking changes before upgrading.

Then run the automated migration command — it rewrites your config in place:

bash Copy

electron-builder migrate-schema

Step-by-step walkthrough: v26 → v27 migration guide · electron.build/docs/migration/v26-to-v27

Installation Copy Chapter

yarn add electron-builder --dev
// or npm, pnpm, bun

Note for Yarn 3 Copy Section

Yarn 3 uses PnP by default, but electron-builder still needs node-modules (ref: yarnpkg/berry#4804). Add configuration in the .yarnrc.yaml as follows:

nodeLinker: "node-modules"

This instructs Yarn to use node-modules instead of PnP.

Quick Setup Guide Copy Chapter

electron-quick-start is the official minimal starter for a new Electron application.

1. Clone the starter and add electron-builder:

   bash Copy

   git clone https://github.com/electron/electron-quick-start
   cd electron-quick-start
   npm install
   npm install electron-builder --save-dev

2. Specify the standard fields in the application package.json — name, description, version and author.

3. Specify the build configuration in the package.json as follows:

   json Copy

   "build": {
     "appId": "your.id",
     "mac": {
       "category": "your.app.category.type"
     }
   }

   See all options. Option files to indicate which files should be packed in the final application, including the entry file, maybe required.
   You can also use separate configuration files, such as js, ts, yml, and json/json5. See read-config-file for supported extensions. JS Example for programmatic API

4. Add icons.

5. Add the scripts key to the development package.json:

   json Copy

   "scripts": {
     "app:dir": "electron-builder --dir",
     "app:dist": "electron-builder"
   }

   Then you can run yarn app:dist (to package in a distributable format (e.g. dmg, windows installer, deb package)) or yarn app:dir (only generates the package directory without really packaging it. This is useful for testing purposes).

   To ensure your native dependencies are always matched electron version, simply add script "postinstall": "electron-builder install-app-deps" to your package.json.

6. If you have native addons of your own that are part of the application (not as a dependency), set nativeModules.nodeGypRebuild to true.

Please note that everything is packaged into an asar archive by default.

For an app that will be shipped to production, you should sign your application. See Where to buy code signing certificates.

Programmatic Usage Copy Chapter

TypeScript types are provided and can be found here. See the full programmatic usage guide.

// ESM (recommended)
import { build, Platform } from "electron-builder"

await build({
  targets: Platform.MAC.createTarget(),
  config: {
    // build options — see https://www.electron.build/
  }
})

// CommonJS — also works on Node >=22.12.0
const { build, Platform } = require("electron-builder")

build({ targets: Platform.MAC.createTarget(), config: {} })
  .then(() => { /* done */ })
  .catch(console.error)

Community Boilerplates Copy Chapter

• electron-react-boilerplate A boilerplate for scalable cross-platform desktop apps.
• electron-vue-vite A real simple Electron + Vue3 + Vite5 boilerplate.
• vite-electron-builder Secure boilerplate for Electron app based on Vite. Supports multiple frameworks.
• electronjs-with-nextjs ElectronJS application with NextJS and TypeScript.

Debug Copy Chapter

Set the DEBUG environment variable to debug what electron-builder is doing:

DEBUG=electron-builder

FPM_DEBUG env to add more details about building linux targets (except snap and appimage).

DEBUG_DMG=true env var to add more debugging/verbosity from hdiutil (macOS).

:::tip[Windows cmd]
On Windows the environment variable is set using the set command.

set DEBUG=electron-builder

:::

:::tip[PowerShell]
PowerShell uses different syntax to set environment variables.

$env:DEBUG = "electron-builder"

:::

If you've identified a bug and want to report it, use electron/minimal-repro to create a minimal reproduction case. Attaching one to your issue significantly speeds up diagnosis.

Donate Copy Chapter

This open source work is accomplished during free time. If you'd like to have more time invested in it, please consider donating.

Overview (`.changeset/README.md`) Copy Section

Changesets

Hello and welcome! This folder has been automatically generated by @changesets/cli, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it in our repository

We have a quick list of common questions to get you started engaging with this project in
our documentation

Overview (`docker/readme.md`) Copy Section

It is developer documentation. See user documentation.

Build

pnpm docker-images

Notes

• We use named data volume instead of mounted host directory to store node_modules because NPM is unreliable and NPM team doesn't want to fix it.

  ${PWD##*/}-node-modules is used as name of data volume — it is your current directory name (e. g. foo) and suffix -node-modules.

  As downside, you have to manually clear outdated data volumes, use docker volume rm your-name.

Overview (`test/README.md`) Copy Section

Test file classes: `*Test.ts` vs `*.e2e.ts`

Packaging tests that need the built installer/archive (mount the dmg, list the nupkg, read latest.yml, run the
installer under wine, …) live in *.e2e.ts files, next to the *Test.ts file of the same area (e.g.
windows/oneClickInstallerTest.ts + windows/oneClickInstaller.e2e.ts). Everything in a *Test.ts file stops once the
app directory is assembled (a dir target, afterPackTestHook, effectiveOptionComputed, or a thrown configuration
error). Generated toolset suites opt in with e2e: true in their SuiteConfig and are emitted as <suite>__<dims>__e2e.ts
(or <suite>__<dims>.win.e2e.ts when platform-gated).

TEST_MODE selects the class: all (default; CI runs both on every PR and master commit), unit or e2e. TEST_FILES
is a substring override and always wins over the mode. Snapshots follow the file name: foo.e2e.ts →
test/snapshots/.../foo.e2e.js.snap.

Inspect output if test uses temporary directory

Set environment variable TEST_APP_TMP_DIR (e.g. /tmp/electron-builder-test).
Specified directory will be used instead of random temporary directory and cleared on each run.

Test Code Signing Ceritificates Copy Chapter

If test installer certificate is expired: http://security.stackexchange.com/questions/17909/how-to-create-an-apple-installer-package-signing-certificate

Overview (`packages/app-builder-lib/README.md`) Copy Section

app-builder-lib

Various utilities. Used by electron-builder.

Overview (`packages/builder-util-runtime/readme.md`) Copy Section

builder-util-runtime

HTTP utilities. Used by electron-builder.

Overview (`packages/builder-util/readme.md`) Copy Section

builder-util

Various utilities. Used by electron-builder.

Overview (`packages/dmg-builder/readme.md`) Copy Section

dmg-builder

Utilities to build DMG. Used by electron-builder.

Overview (`packages/electron-builder-squirrel-windows/readme.md`) Copy Section

electron-builder-squirrel-windows

Plugin for electron-builder to build Squirrel.Windows installer.

Overview (`packages/electron-forge-maker-appimage/readme.md`) Copy Section

electron-installer-appimage

electron-builder appimage target for electron-forge.

Recommended to build electron-forge project using electron-builder directly.
Publishing,
Auto Update
and Code Signing supported only in this case
(including all other useful packaging options like files).

Overview (`packages/electron-forge-maker-nsis-web/readme.md`) Copy Section

electron-forge-maker-nsis-web

electron-builder nsis-web target for electron-forge.

Recommended to build electron-forge project using electron-builder directly.
Publishing,
Auto Update
and Code Signing supported only in this case
(including all other useful packaging options like files).

Overview (`packages/electron-forge-maker-nsis/readme.md`) Copy Section

electron-forge-maker-nsis

electron-builder nsis target for electron-forge.

Recommended to build electron-forge project using electron-builder directly.
Publishing,
Auto Update
and Code Signing supported only in this case
(including all other useful packaging options like files).

Overview (`packages/electron-forge-maker-snap/readme.md`) Copy Section

electron-installer-snap

electron-builder snap target for electron-forge.

Recommended to build electron-forge project using electron-builder directly.
Publishing,
Auto Update
and Code Signing supported only in this case
(including all other useful packaging options like files).

Overview (`packages/electron-publish/readme.md`) Copy Section

electron-publish

Part of electron-builder.

See the Publishing Artifacts for more information.

Can be used standalone.

Overview (`packages/electron-updater/README.md`) Copy Section

electron-updater

This module allows you to automatically update your application. You only need to install this module and write two lines of code!
To publish your updates you just need simple file hosting, it does not require a dedicated server.

See Auto Update for more information.

Supported OS:

• macOS (Squirrel.Mac).
• Windows (NSIS).
• Linux (AppImage, rpm, deb).

Credits Copy Chapter

Thanks to Evolve Labs for donating the npm package name.

Overview (`packages/app-builder-lib/templates/nsis/README.md`) Copy Section

NSIS

⚠️ It is developer documentation. If your are looking for usage guide, see user documentation.

NSIS stands for Nullsoft Scriptable Install System. electron-builder utilizes a customized version of it and uses NsisMultiUser plugin to handle installation for single user or all users on the computer.

Some links Copy Chapter

http://www.mathiaswestin.net/2012/09/how-to-make-per-user-installation-with.html

https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457(v=vs.85).aspx#FOLDERID_UserProgramFiles

https://github.com/Drizin/NsisMultiUser

NSIS vs Inno Setup — it is not easy to choose because both are far from ideal, e.g. inno also doesn't have built-in per-user installation implementation — http://stackoverflow.com/questions/34330668/inno-setup-custom-dialog-with-per-user-or-per-machine-installation.

http://stackoverflow.com/questions/2565215/checking-if-the-application-is-running-in-nsis-before-uninstalling

One-click installer: http://forums.winamp.com/showthread.php?t=300479

Localization (l10n) Copy Chapter

For translators, the strings to be displayed are included in assistedMessages.yml and [messages.yml]https://github.com/electron-userland/electron-builder/blob/master/packages/app-builder-lib/templates/nsis/messages.yml).

As for other strings in NSIS, head to electron-userland/electron-builder-binaries or the upstream repository on Sorceforge.

GUID Copy Chapter

See docs.

We use UUID v5 to generate sha-1 name-based UUID.

http://stackoverflow.com/questions/3029994/convert-uri-to-guid
https://alexandrebrisebois.wordpress.com/2013/11/14/create-predictable-guids-for-your-windows-azure-table-storage-entities/
https://github.com/Squirrel/Squirrel.Windows/pull/658

Compression Copy Chapter

NSIS LZMA compression is slower and worse compared to external 7za compression. Slower because 7za is multi-threaded, worse because LZMA codec implementation is outdated and BCJ2 filter is not enabled.
Difference for test app — 4 MB (before: 36.3 after: 32.8).

And compression time is also greatly reduced.

Since NSIS is awesome, no disadvantages in our approach — compression is disabled before File /oname=app.7z "${APP_ARCHIVE}" and enabled after (it is the reasons why SOLID compression is not used).
So, opposite to Squirrel.Windows, archive is not twice compressed.

So, in your custom NSIS scripts you should not use any compression instructions. Only SetCompress if you need to disable compression for already archived file.

Appimage (`website/docs/appimage.md`) Copy Section

The top-level appImage key contains a set of options instructing electron-builder on how it should build AppImage files.

AppImage is a self-contained, portable Linux application format that packages everything an application needs to run into a single executable file — no installation, no root access required. Under the hood, the application files are stored in a squashfs filesystem that is mounted on launch.

AppImage is one of the two default Linux targets for electron-builder (along with Snap).

AppImage vs. Snap vs. Flatpak vs. DEB Copy Chapter

How AppImage Works Copy Chapter

An AppImage is a single executable file that bundles:

• A runtime binary prepended at the start of the file (handles mounting and launching)
• A squashfs filesystem containing the application and all its dependencies

Running an AppImage Copy Chapter

Make the file executable, then run it directly — no installation or root privileges needed:

chmod +x MyApp-1.0.0-x86_64.AppImage
./MyApp-1.0.0-x86_64.AppImage

Extracting an AppImage Copy Section

You can extract the contents of any AppImage without running it:

./MyApp-1.0.0-x86_64.AppImage --appimage-extract
# Contents are extracted to ./squashfs-root/

This is useful for inspection, manual desktop integration, or debugging.

Desktop Integration Copy Chapter

:::info[Desktop Integration]
Since electron-builder 21, desktop integration (creating .desktop files, associating file types, registering with application menus) is NOT handled by the AppImage itself.
:::

AppImages do not self-integrate with your desktop by default. There are two approaches:

Automatic Integration via AppImageLauncher (recommended) Copy Section

AppImageLauncher integrates AppImages into your application menu and manages updates. Install it from your distribution's package manager or from its releases page.

Once installed, double-clicking an AppImage will prompt you to integrate it. AppImageLauncher handles:

• Creating a .desktop entry in ~/.local/share/applications/
• Placing icons in ~/.local/share/icons/
• Registering MIME type associations

Manual Integration Copy Section

Extract the AppImage (see above) and copy the relevant files:

# Extract
./MyApp-1.0.0-x86_64.AppImage --appimage-extract

# Copy desktop entry and icon
cp squashfs-root/myapp.desktop ~/.local/share/applications/
cp squashfs-root/myapp.png ~/.local/share/icons/hicolor/256x256/apps/

# Update the Exec= line in the .desktop file to point to the AppImage
sed -i "s|Exec=.*|Exec=/path/to/MyApp-1.0.0-x86_64.AppImage|" \
  ~/.local/share/applications/myapp.desktop

# Refresh the desktop database
update-desktop-database ~/.local/share/applications/

Desktop Entry Customization Copy Chapter

Customize the .desktop file metadata embedded in the AppImage via the linux.desktop option:

linux:
  desktop:
    entry:
      Name: My Application
      Comment: A great application
      Categories: Office;Productivity
      Keywords: productivity;tool
      StartupWMClass: myapp
    desktopActions:
      NewWindow:
        Name: New Window
        Exec: myapp --new-window

See Linux Configuration for the full desktop entry reference.

MIME Type Associations Copy Chapter

Associate your AppImage with file types via linux.mimeTypes:

linux:
  mimeTypes:
    - application/x-myapp-document

Auto-Update Support Copy Chapter

AppImages support differential (delta) updates via the electron-updater package. electron-builder embeds a blockmap directly into the AppImage binary at build time — no separate file needs to be published alongside it. electron-updater reads the embedded blockmap to determine which blocks have changed and downloads only those blocks. Configure a publish provider and electron-updater will handle updates:

publish:
  provider: github   # or s3, generic, etc.

See Auto Update for the full setup guide.

Architecture Support Copy Chapter

Build requirements: Linux host (or Docker) for all architectures.

Toolsets Copy Chapter

The AppImage build tools are configured via the top-level toolsets.appimage option. As of v27 the default resolves to the static, FUSE3-compatible runtime; the legacy FUSE2 runtime is available by pinning "0.0.0".

Default — static runtime Copy Section

The default toolset bundles a static AppImage runtime that does not depend on FUSE2. The runtime is prepended directly to the squashfs filesystem and handles mounting internally, so AppImages run on modern distributions (Arch, Fedora, Ubuntu 24.04+) without installing FUSE. Its AppRun entry point also performs smart sandbox detection — it passes --no-sandbox to Electron only when unprivileged user namespaces are unavailable, rather than always.

:::note[v27: default --no-sandbox change]
With the legacy FUSE2 runtime (toolsets.appimage: "0.0.0"), electron-builder injects --no-sandbox by default. With the default static runtime it does not — AppRun adds it only when user namespaces are unavailable. Set executableArgs: ["--no-sandbox"] if you need to force it.
:::

Legacy runtime (`0.0.0`) — FUSE2 Copy Section

Pin toolsets: { appimage: "0.0.0" } only if you specifically need the original FUSE2 runtime. FUSE2 has been unmaintained since 2017 and is increasingly unavailable on modern distributions, where an AppImage built with it fails to launch:

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

toolsets:
  appimage: "0.0.0"   # legacy FUSE2 runtime — only if you need it

Compression Copy Chapter

AppImage files use squashfs internally. The compression algorithm affects file size and launch speed.

:::info[Compression support by toolset]

• Legacy FUSE2 (0.0.0): an explicit appImage.compression of xz or gzip is forwarded to mksquashfs; otherwise the root compression: "maximum" selects xz. All other values use mksquashfs's default (gzip).
• Static runtime (default): supports gzip and zstd. The appImage.compression option selects the algorithm directly; "xz" is mapped to "zstd" (xz is not compiled into the static runtime binary).
  :::

Direct algorithm selection (the legacy 0.0.0 toolset forwards only gzip and xz):

appImage:
  compression: zstd   # gzip | zstd | xz (mapped to zstd)

License Agreement (EULA) Copy Chapter

If your application requires users to accept a license before first launch, set the license option to the path of a .txt or .html file:

appImage:
  license: build/EULA.txt

The license dialog is shown on first launch using zenity, kdialog, or Xdialog (whichever is available). Acceptance is recorded in $XDG_CONFIG_HOME//eulaAccepted.

Build Requirements Copy Chapter

AppImages must be built on Linux (or via Docker). They cannot be cross-compiled from macOS or Windows.

To build on a non-Linux host:

docker run --rm -ti \
  --env-file <(env | grep -iE 'DEBUG|NODE_|ELECTRON_|YARN_|NPM_|CI|CIRCLE|TRAVIS_TAG|TRAVIS|TRAVIS_REPO_|TRAVIS_BUILD_|TRAVIS_BRANCH|TRAVIS_PULL_REQUEST_|APPVEYOR_|CSC_|GH_|GITHUB_|BT_|AWS_|STRIP|BUILD_') \
  --env ELECTRON_CACHE="/root/.cache/electron" \
  --env ELECTRON_BUILDER_CACHE="/root/.cache/electron-builder" \
  -v ${PWD}:/project \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  electronuserland/builder:wine \
  /bin/bash -c "npm install && npx electron-builder --linux"

See Multi Platform Build for full Docker documentation.

Debugging Copy Chapter

Enable verbose output:

DEBUG=electron-builder electron-builder --linux AppImage

Test the built AppImage:

chmod +x dist/MyApp-1.0.0.AppImage
./dist/MyApp-1.0.0.AppImage --no-sandbox

The --no-sandbox flag may be required on some distributions where user namespaces are restricted.

Configuration Copy Chapter

{!./app-builder-lib.Interface.AppImageOptions.md!}

Appx (`website/docs/appx.md`) Copy Section

The top-level appx key contains a set of options instructing electron-builder on how it should build AppX packages for the Windows Store or enterprise sideloading.

All options are optional. All required AppX configuration is inferred and computed automatically.

When to Use AppX Copy Chapter

AppX is the packaging format for the Microsoft Store (also called MSIX). Choose AppX when:

• Windows Store distribution — your app will be listed in the Microsoft Store
• Enterprise sideloading — IT manages app distribution via MDM/Intune without the Store
• Windows 10S / Windows SE — these locked-down Windows editions only run Store apps

For standard consumer distribution, NSIS is simpler. For enterprise deployment without the Store, MSI is often preferred.

AppX vs. NSIS vs. MSI Copy Chapter

Code Signing {#appx-package-code-signing} Copy Chapter

• Store distribution — no manual signing needed. The Windows Store signs the package with a Microsoft certificate during the submission process.
• Sideloading / enterprise — the AppX must be signed with a trusted certificate. See Windows Code Signing.

For self-signed certificates during development, see Microsoft's self-signed certificate guide.

AppX Assets Copy Chapter

AppX requires specific logo/icon assets. Place them in the appx folder inside your build resources directory (default: build/appx/):

Default assets are used for the required logos if you don't provide your own. Scale variants (e.g., Square44x44Logo.scale-200.png) are supported — see Microsoft's tile asset guidelines.

Identity and Publisher Copy Chapter

appx:
  applicationId: "MyApp"                       # must be alphanumeric, no spaces
  identityName: "MyCompany.MyApp"              # unique within the Store
  publisher: "CN=My Company, O=My Company, C=US"  # must match certificate Subject
  publisherDisplayName: "My Company"
  displayName: "My Application"               # displayed in Start menu

:::warning[Publisher Must Match Certificate]
The publisher value must exactly match the Subject field of your code signing certificate. Mismatches cause installation failures.
:::

Capabilities Copy Chapter

AppX apps declare the system capabilities they use. Specify capabilities in appx.capabilities:

appx:
  capabilities:
    - runFullTrust                  # default — allows unrestricted execution
    - internetClient               # outbound internet access
    - privateNetworkClientServer   # local network
    - webcam                       # camera access
    - microphone                   # microphone access

runFullTrust is required for most Electron apps (included by default). The full list of capabilities is in Microsoft's documentation.

Tile Customization Copy Chapter

appx:
  backgroundColor: "#2c2c2c"    # tile background color (CSS color)
  showNameOnTiles: false        # show app name on tile (default: false)

Language Support Copy Chapter

appx:
  languages:
    - en-US
    - de-DE
    - fr-FR
    - ja-JP

Declare which languages your app supports. This affects Store listings and localized resources.

Version Targeting Copy Chapter

appx:
  minVersion: "10.0.17763.0"       # Windows 10 1809 minimum
  maxVersionTested: "10.0.22621.0" # Windows 11 22H2 tested maximum

Auto-Launch Extension Copy Chapter

appx:
  addAutoLaunchExtension: false    # Default: false

When true, adds a startup task extension that runs the app on user login. Requires the runFullTrust capability.

Custom Manifest Copy Chapter

For advanced scenarios, provide a completely custom AppX manifest:

appx:
  customManifestPath: build/AppxManifest.xml

Or inject additional XML extensions:

appx:
  customExtensionsPath: build/appx-extensions.xml

Publishing to the Windows Store Copy Chapter

1. Create a Microsoft Developer account ($19 one-time fee)
2. Reserve your app name in Partner Center
3. Build your AppX: electron-builder --win appx
4. Test the package locally (see Testing below)
5. Upload the .appx file via Partner Center submission
6. Complete the submission (age rating, pricing, screenshots, etc.)
7. Wait for Store certification (typically 1-3 business days)

Sideloading Without the Store Copy Chapter

For enterprise distribution without the Store:

# Enable sideloading (Windows 10 1803+, this is the default)
# On Windows 10 S/SE, you must use the Store

# Install the AppX
Add-AppxPackage -Path ".\MyApp-1.0.0.appx"

If using a self-signed certificate, the user must trust it first (see "Common Questions" below).

Testing Locally Copy Chapter

# Install locally (Developer Mode must be enabled for unsigned packages)
Add-AppxPackage -Path ".\MyApp-1.0.0.appx"

# Uninstall
Get-AppxPackage | Where-Object {$_.Name -like "*MyApp*"} | Remove-AppxPackage

Common Questions Copy Chapter

How do I install an AppX with a self-signed certificate?

Import the certificate into "Trusted People" on the target machine — see Microsoft's guide to signing MSIX packages. Then install the AppX normally with Add-AppxPackage.

Does AppX support auto-updates without the Store?

No — AppX auto-updates are handled by the Windows Store only. electron-updater does not support AppX packages. For auto-updates outside the Store, use NSIS instead.

Configuration Copy Chapter

{!./app-builder-lib.Interface.AppXOptions.md!}

Architecture (`website/docs/architecture.md`) Copy Section

Architecture & Multi-Arch Builds

electron-builder can produce builds for multiple CPU architectures. This page covers architecture support by platform, how to build universal macOS binaries, and cross-compilation considerations.

Supported Architectures by Platform Copy Chapter

:::note[32-bit support ends with Electron 43]
Electron 44 removed Windows ia32 and Linux armv7l builds (electron/electron#51816). To keep shipping those architectures, stay on Electron <= 43.x — the v43 series is supported until its end-of-life in January 2027. electron-builder fails fast with a configuration error when such a build is requested against Electron 44+ (downgraded to a warning when a custom electronDist or Electron mirror is configured).
:::

Specifying Architecture Copy Chapter

CLI Copy Section

# Build for a specific architecture
electron-builder --mac --x64
electron-builder --mac --arm64
electron-builder --mac --universal

# Build multiple architectures in sequence
electron-builder --win --x64 --arm64

# Build for all configured targets and architectures
electron-builder --mac --win --linux

Configuration Copy Section

mac:
  target:
    - target: dmg
      arch:
        - x64
        - arm64
        - universal
    - target: zip
      arch: universal

:::note[v27: arch: "all" now expands to x64 + arm64]
On Windows and Linux, arch: "all" (and the default multi-arch build) expands to x64 + arm64 in v27 — it no longer includes ia32. Request ia32 (or armv7l) explicitly if you still build 32-bit. See What's New in v27.
:::

macOS: Universal Binaries Copy Chapter

A universal binary contains both x64 and arm64 slices in a single executable. It runs natively on Intel Macs and Apple Silicon without Rosetta 2 translation.

Building Universal Copy Section

electron-builder --mac --universal

Or set in configuration:

mac:
  target:
    - target: dmg
      arch: universal

electron-builder downloads both x64 and arm64 Electron binaries, then merges them using lipo.

How ASAR Merging Works Copy Section

When building a universal binary, electron-builder must merge two ASAR archives (one per architecture). This works automatically for pure JavaScript. For native modules:

mac:
  universal:                # v27: universal-build options live under mac.universal
    mergeASARs: true        # Default: true — merge the two per-arch ASARs into one
    singleArchFiles: ""     # Glob of files that must NOT be merged (arch-specific binaries)
    x64ArchFiles: ""        # Glob of files that exist only in the x64 build

Arch-Specific Native Modules Copy Section

If you have native modules that differ between x64 and arm64, you must configure which files should remain architecture-specific:

mac:
  universal:
    mergeASARs: true
    singleArchFiles: "node_modules/canvas/**"   # only exists in x64

For modules that exist in both architectures but have different binaries:

mac:
  universal:
    mergeASARs: true
    x64ArchFiles: "node_modules/my-module/build/Release/my_module.node"

Verifying a Universal Binary Copy Section

# Check that both slices are present
lipo -info dist/mac-universal/MyApp.app/Contents/MacOS/MyApp
# Should output: Architectures in the fat file: x64 arm64

# Check a framework
lipo -info "dist/mac-universal/MyApp.app/Contents/Frameworks/Electron Framework.framework/Electron Framework"

Universal vs. Separate Builds Copy Section

Most consumer apps ship universal binaries for the best user experience. If binary size is critical, ship separate architectures.

Windows ARM64 Copy Chapter

Windows ARM64 builds run natively on ARM-based Windows devices (Surface Pro X, Snapdragon-based laptops, etc.).

electron-builder --win --arm64

:::note[Cross-compilation from x64]
Windows ARM64 builds can be cross-compiled from an x64 Windows machine. The Electron binary for ARM64 is downloaded automatically.
:::

Linux ARM Copy Chapter

Linux ARM builds are commonly used for:

• Raspberry Pi — armv7l (Pi 3 and older) or arm64 (Pi 4+)
• ARM servers — arm64 (AWS Graviton, Ampere Altra, etc.)
• Embedded Linux — armv7l

# For Raspberry Pi 4+ and ARM servers
electron-builder --linux --arm64

# For older Raspberry Pi (32-bit OS)
electron-builder --linux --armv7l

Building Linux ARM on x64 Copy Section

Linux ARM can be built on an x64 machine using QEMU emulation via Docker:

# Install QEMU support (one-time setup)
docker run --privileged --rm tonistiigi/binfmt --install arm64,arm

# Build ARM64 AppImage
docker run --rm \
  -v ${PWD}:/project \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  --platform linux/arm64 \
  electronuserland/builder \
  /bin/bash -c "npm ci && npx electron-builder --linux --arm64"

Cross-Platform Builds Copy Chapter

Building Windows on Linux/macOS Copy Section

Use the Wine-based Docker image:

docker run --rm \
  -v ${PWD}:/project \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  electronuserland/builder:wine \
  /bin/bash -c "npm ci && npx electron-builder --win"

Wine is used to run NSIS (which generates the .exe installer). The Electron binary itself is compiled natively — Wine is only needed for the installer tool.

Building Linux on macOS Copy Section

Linux builds require either a native Linux machine or Docker:

docker run --rm \
  -v ${PWD}:/project \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  electronuserland/builder \
  /bin/bash -c "npm ci && npx electron-builder --linux"

Building AppX on macOS (via Parallels VM) Copy Section

For AppX (Windows Store), MakeAppx.exe requires Windows. When building on macOS with Parallels Desktop (Pro Edition), electron-builder automatically detects and uses the running Windows VM.

See Multi Platform Build for full Docker documentation.

Native Modules and Architecture Copy Chapter

Native modules (.node files) are compiled for a specific architecture and cannot be used in a different architecture without recompilation.

In practice, electron-builder handles this automatically during the build process when nativeModules.npmRebuild: true (the default; in v27 the native-module options npmRebuild, nodeGypRebuild, buildDependenciesFromSource, and rebuildMode live under nativeModules).

:::note[v27: node_modules are arch/os-filtered on every build]
v27 filters node_modules by each package's package.json cpu / os fields against the target arch and platform on every build (previously this effectively only mattered for universal macOS builds). A dependency that declares an incompatible cpu/os for the target is excluded from the packaged app. This is usually what you want; if you intentionally bundle a cross-arch/cross-os optional binary, include it explicitly via extraResources / files.
:::

Universal Binary with Native Modules Copy Section

Building a universal macOS binary with native modules requires that each native module has both x64 and arm64 variants. If a module only has one architecture, you'll need to use singleArchFiles to keep it arch-specific:

mac:
  universal:
    mergeASARs: true
    singleArchFiles: "node_modules/serialport/**/*.node"

Or if you can compile the module for both architectures, the universal build will merge them automatically via lipo.

Architecture in GitHub Actions Copy Chapter

Build multiple architectures in parallel using a matrix:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: macos-latest
            args: --mac --universal
          - os: windows-latest
            args: --win --x64 --arm64
          - os: ubuntu-latest
            args: --linux --x64

    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx electron-builder ${{ matrix.args }} --publish always
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Related Pages Copy Chapter

• GitHub Actions — full CI/CD workflows
• Multi Platform Build — Docker images and cross-compilation
• macOS Configuration — mac.universal.mergeASARs, mac.universal.singleArchFiles, mac.universal.x64ArchFiles
• Target Selection — choosing the right target format per platform

Cli (`website/docs/cli.md`) Copy Section

title: CLI Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

For other commands please see help using --help arg, e.g. ./node_modules/.bin/electron-builder install-app-deps --help

:::tip
npx is bundled with Node.js, so you can simply use npx electron-builder.
:::

:::note[Requirements]
electron-builder v27 requires Node.js >=22.12.0. Upgrading from v26? Review the v27 breaking changes, then follow the migration walkthrough.
:::

`migrate-schema` Copy Chapter

New in v27. Rewrites your build configuration from the v26 shape to the v27 shape in place, applying every config-level breaking change (see the walkthrough).

electron-builder migrate-schema            # apply changes in place
electron-builder migrate-schema --dry-run  # preview without writing (alias: -n)

• Auto-detects your config: the package.json build key, or electron-builder.{yml,yaml,json,json5,toml,js,cjs,mjs,ts}. Pass --config for a non-default file and --project-dir <dir> for the project root.
• Rewrites static configs (json/json5/yaml/package.json) and programmatic ones (.js/.ts/.cjs/.mjs, via an AST codemod that preserves comments and formatting when the config reduces to a single object literal).
• TOML is detected but not rewritten (the toml library is read-only) — it prints the required changes for you to apply. JSON5 is re-serialized as JSON (comments are not preserved).
• Prints a warning for anything it cannot rewrite mechanically (e.g. squirrelWindows.customSquirrelVendorDir) and an advisory for runtime defaults and behavior changes worth checking (an nsis-web target, a per-machine nsis / nsisWeb installer, a custom win.sign.sign hook without a publisher name, a generic publish url with a query string, macOS configs relying on the default entitlements). Advisories never change the file. See what it does and does not do.

:::note[Removed CLI flags]
The v22-era --em.build / --em.directories flags were removed — pass build config inline with -c (e.g. -c.directories.output=dist). Implicit publishing was also removed: pass --publish explicitly.
:::

Prepend npx to sample commands below if you run them from Terminal and not from package.json scripts.

:::note[build for macOS, Windows and Linux]
electron-builder -mwl
:::

:::note[build deb and tar.xz for Linux]
electron-builder --linux deb tar.xz
:::

:::note[build NSIS 32-bit installer for Windows (Electron <= 43 only)]
electron-builder --windows nsis:ia32

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

:::note[set package.json property foo to bar]
electron-builder -c.extraMetadata.foo=bar
:::

:::note[configure unicode options for NSIS]
electron-builder -c.nsis.unicode=false
:::

Target Copy Chapter

Without target configuration, electron-builder builds Electron app for current platform and current architecture using default target.

• macOS - DMG and ZIP for Squirrel.Mac.
• Windows - NSIS.
• Linux:
  • if you build on Windows or macOS: Snap and AppImage for x64.
  • if you build on Linux: Snap and AppImage for current architecture.

Platforms and archs can be configured using CLI args, or in the configuration.

For example, if you don't want to pass --x64 and --arm64 flags each time, but instead build by default NSIS target for all archs for Windows (add ia32 only when staying on Electron <= 43):

:::note[Configuration]

package.json

"build": {
  "win": {
    "target": [
      {
        "target": "nsis",
        "arch": [
          "x64",
          "arm64"
        ]
      }
    ]
  },
  "mac": {
    "target": [
      {
        "target": "dmg",
        "arch": [
          "universal"
        ]
      }
    ]
  }
}

electron-builder.yml

win:
  target:
    - target: nsis
      arch:
        - x64
        - arm64
mac:
  target:
    - target: dmg
      arch: universal

electron-builder.config.js

module.exports = {
  "win": {
    "target": [
      {
        "target": "nsis",
        "arch": [
          "x64",
          "arm64"
        ]
      }
    ]
  },
  "mac": {
    "target": [
      {
        "target": "dmg",
        "arch": [
          "universal"
        ]
      }
    ]
  }
}

:::

and use

build -wl

TargetConfiguration Copy Section

• target String - The target name. e.g. snap.
• arch "x64" | "ia32" | "armv7l" | "arm64" | "universal" - The arch or list of archs.

Configuration (`website/docs/configuration.md`) Copy Section

title: "Configuration" Copy Chapter

{!./partials/_upgrading-from-v26.md!}

electron-builder configuration can be defined

• in the package.json file of your project using the build key on the top level:

  json Copy

  "build": {
    "appId": "com.example.app"
  }

• or through the --config option. Defaults to electron-builder.yml.

  yaml Copy

  appId: "com.example.app"

  json, json5, toml or js/ts (exported configuration or function that produces configuration) formats are also supported.

  :::tip
  If you want to use a js file, do not name it electron-builder.js. It will conflict with the electron-builder package name.
  :::

  :::tip
  If you want to use toml, install it with npm install toml --save-dev.
  :::

Most of the options accept null — for example, to explicitly set that DMG icon must be default volume icon from the OS and default rules must be not applied (i.e. use application icon as DMG icon), set dmg.icon to null.

Artifact File Name Template Copy Chapter

${ext} macro is supported in addition to file macros.

Environment Variables from File Copy Chapter

Env file electron-builder.env in the current dir (example). Supported only for CLI usage.

Effective Configuration Copy Chapter

Before packaging, electron-builder writes the resolved configuration to builder-effective-config.yaml in the output directory (directories.output, dist by default). It is the merged result of package.json, the config file, presets and CLI overrides, plus values detected during the build such as electronVersion. Sensitive fields (passwords, tokens, cscLink) are masked.

By default the file is written only for local interactive builds, not on CI or when stdout is piped. Set writeEffectiveConfig to true to always write it (e.g. electron-builder -c.writeEffectiveConfig=true in a CI step), or to false to never write it.

How to Read Docs Copy Chapter

• Name of optional property is normal, required is bold.
• Type is specified after property name: Array<String> | String. Union like this means that you can specify or string (**/*), or array of strings (["**/*", "!foo.js"]).

Common Configuration Copy Section

{!./app-builder-lib.Interface.CommonConfiguration.md!}

Overridable per Platform Options Copy Chapter

Following options can be set also per platform (top-level keys mac, linux and win) if need.

Base Configuration Copy Chapter

{!./app-builder-lib.Interface.PlatformSpecificBuildOptions.md!}

Metadata Copy Chapter

Some standard fields should be defined in the package.json.

{!./app-builder-lib.Interface.Metadata.md!}

Electron Download & Mirror Copy Chapter

electron-builder downloads the Electron distribution to package via @electron/get. Point it at a mirror (e.g. a corporate proxy or a China mirror) with the electronGet option:

{
  "build": {
    "electronGet": {
      "mirrorOptions": { "mirror": "https://npmmirror.com/mirrors/electron/" }
    }
  }
}

:::note[v27: renamed from electronDownload]
This key was electronDownload in v26. In v27 it is electronGet, reshaped to @electron/get v5 options: the flat mirror moved under mirrorOptions.mirror, isVerifyChecksum: false became unsafelyDisableChecksums: true, and cache / customDir / customFilename / strictSSL / force were dropped. electron-builder migrate-schema performs the rename. See v27 Breaking Changes → electronGet.
:::

Build Version Management Copy Chapter

CFBundleVersion (macOS) and FileVersion (Windows) will be set automatically to version.build_number on CI server (Travis, AppVeyor, CircleCI and Bamboo supported).

Build Hooks Copy Chapter

{!./features/hooks.md!}

Contents (`website/docs/contents.md`) Copy Section

Application Contents

This page covers how electron-builder determines which files are included in the packaged app and how to customize file inclusion.

How electron-builder Collects Files Copy Chapter

electron-builder uses a two-phase approach to build the app bundle:

1. App files — your application source code and assets, placed inside the ASAR archive (or directly in the app folder if ASAR is disabled)
2. Extra files/resources — additional files copied into specific locations in the output package, outside the ASAR archive

Default File Inclusion Copy Chapter

By default, electron-builder includes all files matching **/* from the app directory, minus a comprehensive set of automatically-excluded files:

Always excluded:

• node_modules dev dependencies (only production dependencies are included)
• *.iml, *.o, *.hprof, *.pyc, *.pyo, *.rbc, *.swp, .csproj, .sln, .slnx, .xproj
• .editorconfig, ._*, .DS_Store, .git, .hg, .svn, .gitignore, .gitattributes
• __pycache__, .flowconfig, .idea, .vs, .nyc_output
• appveyor.yml, .travis.yml, circle.yml
• npm-debug.log, yarn.lock, .yarn-integrity, .yarn-metadata.json
• Test directories: {test,__tests__,tests,powered-test,example,examples} inside node_modules
• *.d.ts files inside node_modules
• node_modules/.bin

These exclusions are always applied even when you define custom patterns.

The `files` Option Copy Chapter

Override which files are included using the files option. Patterns are glob expressions relative to the app directory:

files:
  - "**/*"
  - "!src/**"           # exclude source files
  - "!tests/**"         # exclude test directory
  - "!**/*.map"         # exclude source maps
  - "dist/**"           # include dist directory

Important behavior:

• If any pattern does NOT start with ! (i.e., it's an include pattern), the default **/* pattern is NOT automatically prepended. You must include it explicitly if you want to start from all files.
• package.json and node_modules/**/* (production only) are always included regardless of patterns.
• All default ignores (listed above) are always applied.

Simple Include Example Copy Section

files:
  - "**/*"
  - "!src/**"
  - "!*.ts"
  - "!tsconfig*.json"

Only Include Specific Directories Copy Section

files:
  - dist/**
  - assets/**
  - node_modules/**     # production node_modules (already automatic)
  - package.json        # always included, but can be explicit

Exclude Large Unused Files Copy Section

files:
  - "**/*"
  - "!node_modules/**/README*"
  - "!node_modules/**/*.md"
  - "!node_modules/**/*.map"
  - "!**/test/**"
  - "!**/__tests__/**"

FileSet Objects Copy Chapter

For advanced scenarios, use FileSet objects instead of (or alongside) glob strings. FileSets let you copy files from a different source directory:

files:
  - from: dist
    to: .
    filter:
      - "**/*"
      - "!**/*.map"
  - from: assets
    to: assets

Renaming a File Copy Section

files:
  - from: dist/main.js
    to: app.js

Copying from Outside the App Directory Copy Section

files:
  - "**/*"
  - from: ../shared/assets
    to: shared-assets

Extra Files and Resources Copy Chapter

Copy files into the packaged app outside the ASAR archive:

`extraResources` Copy Section

Copies into the resources/ directory:

• macOS: MyApp.app/Contents/Resources/
• Windows/Linux: resources/

extraResources:
  - from: native-binaries/
    to: bin
    filter:
      - "**/*"
  - "assets/icon.png"     # string shorthand — copies to resources/assets/icon.png

`extraFiles` Copy Section

Copies into the app content directory:

• macOS: MyApp.app/Contents/
• Windows/Linux: the install directory root

extraFiles:
  - from: config/
    to: config
  - "LICENSE"

:::tip[Native Modules and Extra Binaries]
Use extraResources for native binaries, CLI tools, or data files that need to be accessible at runtime. Access them in your app via process.resourcesPath.
:::

ASAR Packaging Copy Chapter

ASAR is Electron's archive format — it bundles all app files into a single app.asar file for faster loading and to prevent casual file inspection.

asar: {}    # ASAR is enabled by default — pass an object to configure, or set asar: false to disable

Set asar: false to disable ASAR packaging (all files are placed in the app directory directly). Useful for debugging or if you have unusual file access patterns.

Unpacking Files from ASAR Copy Section

Some files cannot be inside an ASAR archive:

• Native modules (.node files)
• Large binary assets that need random-access reads
• Files that need to be executed directly

Use asar.unpack to unpack specific files into app.asar.unpacked/:

asar:
  unpack:
    - "**/*.node"                   # all native modules
    - "resources/ffmpeg"            # large binary
    - "**/**/node_modules/sharp/**" # specific module

Files in app.asar.unpacked/ are accessible via the same paths as if they were in the ASAR — Electron transparently redirects reads.

Smart Unpack Copy Section

asar:
  smartUnpack: true    # Default: true

When enabled, electron-builder automatically detects executables and native modules and unpacks them from ASAR. You generally don't need to configure asar.unpack manually unless you have unusual cases.

ASAR Ordering Copy Section

Optimize app startup time by specifying file ordering within the ASAR archive. Files listed first are packed first, enabling faster sequential reads at startup:

asar:
  ordering: build/asar-ordering.txt

# build/asar-ordering.txt — list files loaded at startup first
index.js
renderer.js
node_modules/electron/index.js

Practical Examples Copy Chapter

Electron App with Native Modules Copy Section

files:
  - "**/*"
  - "!src/**"
  - "!**/*.ts"
  - "!**/*.map"
asar:
  unpack:
    - "**/*.node"

App with Large Video Assets Copy Section

files:
  - "**/*"
  - "!src/**"
  - "!videos/**"      # exclude from ASAR
extraResources:
  - from: videos/
    to: videos         # place outside ASAR, accessible via process.resourcesPath

Monorepo Setup (Two-Package Structure) Copy Section

directories:
  app: packages/app   # app directory is not the project root

files:
  - "**/*"
  - "!src/**"

See Two package.json Structure for the full monorepo setup.

Including Default-Excluded Files Copy Chapter

electron-builder excludes a set of development-only file extensions and names by default — for example
build artifacts such as .obj, .o, .a, and .d.ts, lockfiles such as yarn.lock and
package-lock.json, and VCS/tooling metadata such as .git, .idea, and .github.

To ship a file that would otherwise be excluded, add an explicit files glob that targets it. An
explicit include overrides the matching default exclusion:

files:
  - "**/*"
  - "**/*.obj"        # keep Wavefront .obj 3D models that are excluded by default

The same applies to default-excluded names — reference the name in a pattern segment, e.g.:

files:
  - "**/*"
  - "**/.github/**"   # keep the .github directory that is excluded by default

Only patterns that name an extension or directory concretely opt it back in; broad patterns such as
**/* continue to honor the defaults.

Troubleshooting Copy Chapter

File is missing from packaged app: Check if the file is being excluded by a pattern. Run DEBUG=electron-builder electron-builder build to see detailed file collection output.

Native module crashes at runtime: The module likely needs to be outside the ASAR archive. Add it to asar.unpack:

asar:
  unpack:
    - "node_modules/better-sqlite3/**"

App directory is too large: Profile what's included by examining the app bundle after building. Common culprits: source maps (*.map), TypeScript source files (*.ts), and large test fixtures.

FileSet from path not found: Remember that from in files is relative to the app directory. For extraResources/extraFiles, it's relative to the project root.

File Contents Configuration Copy Chapter

{!./app-builder-lib.Interface.FilesBuildOptions.md!}

FileSet Configuration Copy Chapter

{!./app-builder-lib.Interface.FileSet.md!}

Dmg (`website/docs/dmg.md`) Copy Section

title: "DMG" Copy Chapter

The top-level dmg key contains a set of options instructing electron-builder on how it should build DMG (macOS disk image) files.

When to Use DMG Copy Chapter

DMG is the standard distribution format for direct-download macOS apps. Users mount the disk image, drag the app to their Applications folder, and eject the image. Use DMG when:

• Distributing directly from your website or GitHub Releases
• Using electron-updater (the zip target also runs alongside DMG)
• You want the most familiar macOS install experience

For Mac App Store distribution, see MAS. For system-level installs (kernel extensions, launch daemons), see PKG.

Window Customization Copy Chapter

The window option controls the Finder window that appears when the DMG is mounted:

dmg:
  window:
    position:
      x: 130
      y: 220
    size:
      width: 540
      height: 380

Standard DMG windows are 540×380 pixels. The position coordinates place the window on screen — x: 130, y: 220 is a common convention.

Background Image Copy Chapter

Set a background image to make your DMG installer look polished:

dmg:
  background: build/background.png

Requirements:

• Format: PNG (recommended for quality and transparency support)
• Size: match your window.size — typically 540×380 pixels
• For Retina displays: provide a @2x version at 1080×760 and name it [email protected]. electron-builder will automatically use the high-resolution version on Retina screens.

If no background image is set, use backgroundColor to set a solid color:

dmg:
  backgroundColor: "#2c2c2c"

Icon Layout Copy Chapter

The contents array defines the position and type of icons inside the DMG window. A typical layout has the app icon on the left and a /Applications shortcut on the right:

dmg:
  contents:
    - x: 130
      y: 220
      type: file
    - x: 410
      y: 220
      type: link
      path: /Applications

:::tip[Centering Icons]
For a 540×380 window with two icons, the standard horizontal positions are x=130 (app) and x=410 (Applications link), both at y=220 (vertically centered).
:::

Volume Icon and Title Copy Chapter

The DMG volume appears in the macOS Finder sidebar when mounted. Customize its appearance:

dmg:
  # Badge icon shown in Finder when the DMG is mounted
  badgeIcon: build/icon.icns

  # Volume icon (what appears as the disk image itself in Finder)
  icon: build/volume-icon.icns

  # Title shown in the Finder window title bar when mounted
  title: "${productName} ${version}"

  # Icon size inside the DMG window
  iconSize: 80

  # Font size for icon labels
  iconTextSize: 12

The default title is ${productName} ${version}. The default iconSize is 80 pixels.

Disk Image Format Copy Chapter

The format option controls the compression algorithm:

For most cases, leave format at the default UDZO. Use ULFO if you are targeting macOS 10.11+ and want faster mount times for large apps. Use ULMO if you are targeting macOS 10.15+ and want the smallest download — it typically compresses an Electron app's DMG ~30% smaller than UDZO, at the cost of a few extra seconds to mount and copy at install time.

Volume Filesystem Copy Chapter

The filesystem option controls the filesystem of the DMG volume:

dmg:
  filesystem: "HFS+"   # only for pre-10.13 (High Sierra) compatibility

:::note[v27 default change]
The default changed from HFS+ to APFS in v27. This is a runtime default, not a config-key rename, so migrate-schema does not change it — set filesystem: "HFS+" explicitly if you need the old behavior. See v27 Breaking Changes → DMG filesystem.
:::

DMG Size Copy Chapter

The size option sets the initial filesystem size. Normally this is computed automatically — only set it if you encounter errors about insufficient space during DMG creation:

dmg:
  size: "500m"

Set shrink: false to disable automatic shrinking of the DMG to the minimum size after creation (not recommended for production).

Signing the DMG Copy Chapter

The DMG itself can be signed separately from the app bundle inside it:

dmg:
  sign: true   # Default: false

:::note
The app bundle inside the DMG is always signed (when signing is configured). The sign option here refers to signing the DMG container file itself. Signing the DMG is not required for Gatekeeper but may be requested in some enterprise environments.
:::

Internet-Enabled DMGs Copy Chapter

dmg:
  internetEnabled: true   # Default: false

Internet-enabled DMGs automatically extract their contents and eject after first open. This is an older pattern and is no longer recommended for modern apps.

DMG License Copy Chapter

To display a license agreement when users open the DMG, set the license option in your DMG configuration or use the file-naming convention.

Configuration-based (recommended) Copy Section

Specify the license file path directly in electron-builder.yml:

dmg:
  license: "build/license.rtf"

For multi-language builds, provide a language-code → file-path map:

dmg:
  license:
    en_US: "build/license.rtf"
    de_DE: "build/license_de.txt"
    fr_FR: "build/license_fr.txt"
    ja_JP: "build/license_ja.txt"
    zh_CN: "build/license_zh.txt"

Language codes use the ll_CC format (ISO 639-1 language code + ISO 3166-1 country code, underscore-separated). The first entry in the map is the fallback shown when the user's language is not present.

Supported file formats: .rtf (recommended for rich text), .txt (plain text), .html.

:::tip[RTF recommended]
Use .rtf format for the best cross-language compatibility. Plain .txt files for Japanese, Korean, and Simplified/Traditional Chinese require macOS's CJK codec support in the bundled Python runtime.
:::

File-naming convention (automatic discovery) Copy Section

As an alternative, place license files in your build resources directory using this naming pattern — electron-builder will pick them up automatically:

The language code is derived from the _LANG suffix. The user's macOS language preference determines which license is shown; en_US is the fallback.

:::note[One file per language]
Having both license_en.txt and eula_en.txt in the same build resources directory is an error — both map to en_US and electron-builder will throw an InvalidConfigurationError. Use the config-based license map if you need to control which file is used.
:::

Customizing License Button Labels Copy Section

Override the default button text (Agree / Disagree / Print / Save) for each language by creating licenseButtons_LANG.json or licenseButtons_LANG.yml files in your build resources directory:

{
  "languageName": "English",
  "agree": "Accept",
  "disagree": "Decline",
  "print": "Print",
  "save": "Save",
  "message": "Please read the license agreement below."
}

Name the file licenseButtons_en.json for English, licenseButtons_de.json for German, etc. The message field sets the prompt text at the top of the dialog. The legacy description field is also accepted as an alias for message.

Complete Example Copy Chapter

dmg:
  background: build/dmg-background.png
  window:
    position:
      x: 130
      y: 220
    size:
      width: 540
      height: 380
  contents:
    - x: 130
      y: 220
      type: file
    - x: 410
      y: 220
      type: link
      path: /Applications
  iconSize: 80
  iconTextSize: 12
  title: "${productName} ${version}"
  format: UDZO
  # Single-language license
  license: "build/license.rtf"

Multi-language example:

dmg:
  background: build/dmg-background.png
  license:
    en_US: "build/license.rtf"
    de_DE: "build/license_de.txt"
    fr_FR: "build/license_fr.txt"
  window:
    size:
      width: 540
      height: 380
  format: UDZO

Troubleshooting Copy Chapter

Icons appear in wrong positions: The x and y values in contents are absolute pixels from the top-left of the DMG window. Double-check that your coordinates are within the window.size bounds.

Background not appearing: Ensure the background image exactly matches the window.size dimensions. For Retina support, provide a @2x version at double the resolution.

DMG too large: The default UDZO format compresses well. If size is critical, try UDBZ for better (slower) compression.

License not appearing: If using the config option, verify the license path resolves relative to your build resources directory or project root. If using the file-naming convention, confirm the file is in the build resources directory with the correct pattern (license_en.txt, eula_en.txt, etc.) and a supported extension (.rtf, .txt, .html).

"Multiple license files found" error: You have both license_en.txt and eula_en.txt (or two files that resolve to the same language code) in your build resources. Remove the duplicate or use the config-based license map to point to the exact file you want.

CJK license not appearing: Japanese, Korean, and Chinese plain-text licenses require CJK codec support in the dmgbuild Python runtime. Use .rtf format for these languages, or ensure your dmgbuild bundle version is 1.2.5 or later.

Configuration Copy Chapter

{!./app-builder-lib.Interface.DmgOptions.md!}

Donate (`website/docs/donate.md`) Copy Section

title: Donate Copy Chapter

electron-builder is free, open-source software driven through personal development time and community contributions.

This open-source work is done during free time. If you find it valuable, please consider donating!

Environment Variables (`website/docs/environment-variables.md`) Copy Section

title: "Environment Variables" Copy Chapter

Environment Variables

electron-builder reads a handful of environment variables — almost all of them secrets (signing certificates, publish tokens) or CI-provided values (the release tag, repository slug). Everything else is configured through your configuration file, not the environment.

This page is a grouped reference for every environment variable electron-builder itself reads. For the deeper "how", each group links to the relevant guide.

:::warning[Upgrading from v26?]
Several environment variables were removed in v27 — most notably CI_BUILD_TAG (use CI_COMMIT_TAG), ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY, and every toolset-override variable (USE_SYSTEM_WINE, ELECTRON_BUILDER_NSIS_DIR, …). See Removed in v27 below and the v27 breaking changes.
:::

Code signing Copy Chapter

Signing credentials are read from the environment so certificates and passwords never have to live in your config. Never commit them to source control — inject them via CI secrets. Each value accepts an HTTPS URL, a file:// path, a local path, or a base64-encoded certificate string.

Shared / macOS Copy Section

macOS installer (PKG) Copy Section

Windows Copy Section

:::tip[Cross-compiling Windows on macOS]
Use WIN_CSC_LINK / WIN_CSC_KEY_PASSWORD to supply a separate Windows certificate while keeping your macOS certificate in CSC_LINK / CSC_KEY_PASSWORD.
:::

:::note[More signing variables]
The macOS keychain/identity variables (CSC_NAME, CSC_IDENTITY_AUTO_DISCOVERY, CSC_KEYCHAIN) and Azure Trusted Signing variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) are documented in the code-signing guides: Code Signing, macOS, and Windows. In v27, WIN_CSC_LINK fallback applies only to signtool mode; hsm, pkcs11, and azure are configured through win.sign.
:::

Notarization (macOS) Copy Chapter

For notarizing macOS apps distributed outside the Mac App Store. Provide one of the three credential sets. Full setup is in the Notarization guide.

Publishing Copy Chapter

Publish providers read their credentials from the environment. Publishing is never automatic — you must pass --publish explicitly (see Publish).

GitHub Copy Section

GitLab Copy Section

Bitbucket Copy Section

:::warning[v27 auth change]
In v27 the Bitbucket publisher selects its auth scheme by whether a username is present:

• BITBUCKET_USERNAME set → HTTP Basic auth. Use this for an app password or an Atlassian API token.
• No username → the token is sent as Authorization: Bearer <token> (a repository / project / workspace access token).

If BITBUCKET_TOKEN holds an app password or API token, you must also set BITBUCKET_USERNAME. See the breaking-change note.
:::

Keygen Copy Section

Cloudflare R2 Copy Section

Amazon S3 Copy Section

DigitalOcean Spaces Copy Section

Snap Store Copy Section

See Snap → Authentication for the credential resolution order.

CI and release tags Copy Chapter

electron-builder detects the release tag and repository from standard CI variables. These are normally set by your CI provider, not by you — the exception is CI_COMMIT_TAG, which you can set manually (e.g. on GitLab or self-hosted CI) to provide the tag.

The GitHub repository is auto-detected from TRAVIS_REPO_SLUG, APPVEYOR_REPO_NAME, or CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME (falling back to your package.json repository field or .git/config).

:::warning[CI_BUILD_TAG removed in v27]
CI_BUILD_TAG was removed — use CI_COMMIT_TAG instead. See the breaking-change note.
:::

Cache & download Copy Chapter

:::note[Electron mirror is config, not an env var]
To download Electron from a mirror, configure electronGet.mirrorOptions in your build config — e.g. electronGet: { mirrorOptions: { mirror: "https://my-mirror/" } }. (In v26 this was electronDownload.mirror.) See Configuration.
:::

Debugging Copy Chapter

DEBUG=electron-builder electron-builder --linux snap

Namespaced channels are also available — e.g. DEBUG=electron-builder:7z for archive operations, or DEBUG=electron-builder* for everything.

Removed in v27 Copy Chapter

These variables were removed in v27. electron-builder migrate-schema does not rewrite them — update your scripts and config manually.

Toolset overrides Copy Section

The environment variables that pointed electron-builder at custom build-tool bundles are all removed. Supply a custom bundle through a ToolsetCustom object on the relevant toolsets key instead (toolsets.<name>: { url, checksum }).

The two signing USE_SYSTEM_* variables (USE_SYSTEM_SIGNCODE, USE_SYSTEM_OSSLSIGNCODE) have no env-var replacement — configure signing through win.sign and the winCodeSign toolset. For the full replacement mechanics (archive formats, checksums, file:// directories), see Toolset env-var overrides removed.

File Patterns (`website/docs/file-patterns.md`) Copy Section

title: "File Patterns" Copy Chapter

• * Matches 0 or more characters in a single path portion
• ? Matches 1 character
• [...] Matches a range of characters, similar to a RegExp range.
  If the first character of the range is ! or ^ then it matches
  any character not in the range.
• !(pattern|pattern|pattern) Matches anything that does not match
  any of the patterns provided.
• ?(pattern|pattern|pattern) Matches zero or one occurrence of the
  patterns provided.
• +(pattern|pattern|pattern) Matches one or more occurrences of the
  patterns provided.
• *(a|b|c) Matches zero or more occurrences of the patterns provided
• @(pattern|pat*|pat?erN) Matches exactly one of the patterns
  provided
• ** If a "globstar" is alone in a path portion, then it matches
  zero or more directories and subdirectories searching for matches.
  It does not crawl symlinked directories.

If directory matched, all contents are copied. So, you can just specify foo to copy foo directory.

:::tip[Excluding directories]
Remember that !doNotCopyMe/**/* would match the files in the doNotCopyMe directory, but not the directory itself, so the empty directory would be created.
Solution — use macro ${/*}, e.g. !doNotCopyMe${/*}.
:::

Multiple Glob Patterns Copy Chapter

[
  // match all files
  "**/*",

  // except for js files in the foo/ directory
  "!foo/*.js",

  // unless it's foo/bar.js
  "foo/bar.js",
]

Default Ignored Files Copy Chapter

electron-builder excludes a set of files from the packaged app by default (development files, and certain extensions/names such as Wavefront .obj 3D models). In v27 the disableDefaultIgnoredFiles option was removed. To keep a file that is excluded by default, add an explicit files glob that names it concretely — an explicit include now overrides the matching default exclusion:

{
  "build": {
    "files": [
      "**/*",
      "**/*.obj"  // opt a default-excluded extension back in
    ]
  }
}

Broad patterns such as **/* still honor the defaults; only a pattern that names the extension or directory concretely opts it back in. See v27 Breaking Changes → disableDefaultIgnoredFiles.

File Macros Copy Chapter

You can use macros in the file patterns, artifact file name patterns and publish configuration url:

• ${arch} — expanded to ia32, x64. If no arch, macro will be removed from your pattern with leading space, - and _ (so, you don't need to worry and can reuse pattern).
• ${os} — expanded to mac, linux or win according to target platform.
• ${platform} — expanded to darwin, linux or win32 according to Node.js process.platform property.
• ${name} – package.json name.
• ${productName} — Sanitized product name.
• ${version}
• ${channel} — detected prerelease component from version (e.g. beta).
• ${env.ENV_NAME} — any environment variable.
• Any property of AppInfo (e.g. buildVersion, buildNumber).

Flatpak (`website/docs/flatpak.md`) Copy Section

:::warning[Single-file Flatpak bundles]
Currently electron-builder does not support publishing apps to Flatpak repositories like Flathub. Flatpak support in electron-builder is limited to generating single-file bundles which have limitations compared to apps installed from a repository.
:::

The top-level flatpak key contains a set of options instructing electron-builder on how it should build a Flatpak bundle.

What is Flatpak? Copy Chapter

Flatpak is a universal Linux packaging system that runs apps in a sandbox with controlled access to system resources. Unlike AppImage (no sandbox) and Snap (Ubuntu-primary), Flatpak is designed to be distro-agnostic and runs on any Linux distribution with flatpak installed.

Key characteristics:

• Sandboxed — apps run in an isolated environment with portal-based access to system resources
• Cross-distro — works on Ubuntu, Fedora, Arch, Debian, and more
• Runtime-based — apps are built against a specific runtime (freedesktop, GNOME, KDE)
• Distributed via Flathub (for repository-based distribution — note: currently not supported by electron-builder)

Flatpak vs. AppImage vs. Snap Copy Chapter

Build Requirements Copy Chapter

Install flatpak and flatpak-builder on your Linux build machine — see Flatpak setup.

Runtime and SDK Copy Chapter

Flatpak apps run against a runtime that provides base libraries. Choose the runtime that matches your app's dependencies:

flatpak:
  runtime: org.freedesktop.Platform         # freedesktop (most common for Electron)
  sdk: org.freedesktop.Sdk
  runtimeVersion: "24.08"                   # runtime version

Common runtimes for Electron apps:

Install the runtime on your build machine before building — see available Flatpak runtimes.

Finish Args (Permissions) Copy Chapter

The finishArgs array defines what the sandboxed app is allowed to access. Electron apps need several permissions:

flatpak:
  finishArgs:
    # Display
    - "--socket=x11"
    - "--socket=wayland"
    - "--share=ipc"              # shared memory with X11 compositor
    # Network
    - "--share=network"
    # Filesystem
    - "--filesystem=home"        # access user home directory
    # Desktop integration
    - "--talk-name=org.freedesktop.Notifications"
    - "--talk-name=org.kde.StatusNotifierWatcher"
    - "--talk-name=com.canonical.AppMenu.Registrar"
    # Electron-specific
    - "--device=dri"             # GPU access
    - "--socket=pulseaudio"      # audio

Common finish args for Electron:

Branch Copy Chapter

flatpak:
  branch: stable    # Default: master/main

The branch name is embedded in the Flatpak bundle and visible to users.

Extra Modules Copy Chapter

Include additional system libraries not in the runtime:

flatpak:
  modules:
    - name: zlib
      buildsystem: autotools
      sources:
        - type: archive
          url: https://www.zlib.net/zlib-1.3.tar.gz
          sha256: "..."

Custom Files and Symlinks Copy Chapter

Copy additional files into the app bundle:

flatpak:
  files:
    - - build/extra-binary        # source
      - /app/bin/extra-binary     # destination (absolute within Flatpak)
  symlinks:
    - - /app/bin/myapp            # target
      - /app/bin/myapp-alias      # symlink location

Wayland Support Copy Chapter

flatpak:
  useWaylandFlags: true   # Appends --enable-features=UseOzonePlatform --ozone-platform=wayland when running under a Wayland session

Local Testing Copy Chapter

Build and install the Flatpak locally:

electron-builder --linux flatpak
# This produces a .flatpak bundle file

# Install it (no root required)
flatpak install --user dist/myapp-1.0.0.flatpak

# Run it
flatpak run com.mycompany.myapp

Troubleshooting Copy Chapter

If the build fails, enable debug logging to see the underlying flatpak-builder output:

env DEBUG="@malept/flatpak-bundler" electron-builder build --linux flatpak

Missing runtime: Install the runtime before building — see the Runtime section above.

Sandbox permission denied: Check the finishArgs — the app is likely trying to access something not in its allowed permissions. Run flatpak run --log-session-bus com.mycompany.myapp to see D-Bus access denials.

GPU rendering issues: Ensure --device=dri is in finishArgs for WebGL support.

Configuration Copy Chapter

{!./app-builder-lib.Interface.FlatpakOptions.md!}

Github Actions (`website/docs/github-actions.md`) Copy Section

GitHub Actions CI/CD

This guide shows how to build, sign, and publish Electron apps using GitHub Actions for all three platforms (macOS, Windows, Linux).

Basic Concepts Copy Chapter

• Secrets — store certificates, passwords, and API tokens in GitHub repository secrets (Settings → Secrets and variables → Actions)
• Matrix builds — build for multiple platforms in parallel using a matrix strategy
• GH_TOKEN — the GitHub token electron-builder uses to upload release assets. Use GITHUB_TOKEN (provided automatically) or a PAT with repo scope

Minimal Multi-Platform Workflow Copy Chapter

This workflow builds for macOS, Windows, and Linux on every push to main and on version tags:

name: Build and Release

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  build:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npx electron-builder --publish never
        env:
          # macOS signing
          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
          # Windows signing
          WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
          WIN_CSC_KEY_PASSWORD: ${{ secrets.WIN_CSC_KEY_PASSWORD }}

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-${{ matrix.os }}
          path: dist/

Publish on Tag Push Copy Chapter

To publish GitHub releases automatically when you push a version tag (v1.2.3):

name: Release

on:
  push:
    tags: ['v*']

jobs:
  release:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Publish
        run: npx electron-builder --publish always
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # macOS signing + notarization
          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          # Windows signing
          WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
          WIN_CSC_KEY_PASSWORD: ${{ secrets.WIN_CSC_KEY_PASSWORD }}

The --publish always flag uploads artifacts to the GitHub release for the pushed tag. If no release exists, electron-builder creates a draft release.

Draft Release Workflow Copy Chapter

A common pattern is to publish a draft release on every tagged push, then manually promote it to a full release after reviewing:

# In electron-builder.yml
publish:
  provider: github
  releaseType: draft

Then in GitHub: go to Releases → find the draft → click "Edit" → "Publish release".

macOS Code Signing Setup Copy Chapter

Preparing the Certificate Copy Section

# Export your Developer ID Application certificate from Keychain Access
# File → Export Items → save as .p12 with a password

# Encode to base64
base64 -i certificate.p12 | pbcopy   # copies to clipboard

Add to GitHub Secrets:

• MAC_CSC_LINK — the base64-encoded .p12 content
• MAC_CSC_KEY_PASSWORD — the certificate password

macOS Signing Copy Section

Pass CSC_LINK and CSC_KEY_PASSWORD directly — electron-builder creates and manages a temporary keychain automatically:

build-mac:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build and notarize
        run: npx electron-builder --mac --publish always
        env:
          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

macOS Secrets Reference Copy Section

Windows Code Signing Setup Copy Chapter

# Encode your Windows certificate (.pfx) to base64
# PowerShell:
[Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.pfx")) | Out-File cert_encoded.txt

# bash (Linux/macOS):
base64 certificate.pfx > cert_encoded.txt

Add to GitHub Secrets:

• WIN_CSC_LINK — base64-encoded .pfx content
• WIN_CSC_KEY_PASSWORD — certificate password

Using Azure Trusted Signing Copy Section

- name: Build and sign (Azure)
        run: npx electron-builder --win --publish always
        env:
          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Configure win.sign with type: "azure" in your electron-builder config. See Windows Code Signing.

Caching for Faster Builds Copy Chapter

Cache npm packages and Electron binaries to avoid redundant downloads:

- uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm    # caches ~/.npm

      - name: Cache Electron
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/electron
            ~/.cache/electron-builder
          key: ${{ runner.os }}-electron-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-electron-

Linux Snapcraft Publishing Copy Chapter

To publish to the Snap Store, add a SNAPCRAFT_STORE_CREDENTIALS secret (obtained by running snapcraft export-login -):

- name: Build and publish Snap
        run: npx electron-builder --linux snap --publish always
        env:
          SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Complete Production Workflow Copy Chapter

A production-grade workflow with separate jobs per platform, caching, and GitHub release publishing:

/* Detailed source-code truncated for AI context efficiency. */

Troubleshooting Copy Chapter

"Resource not accessible by integration"
: The workflow doesn't have permission to create releases. Add permissions: contents: write to the job or workflow. Also ensure GH_TOKEN is set.

macOS: "No identity found"
: CSC_LINK or CSC_KEY_PASSWORD is wrong or missing. Verify the base64-encoded certificate decodes to a valid .p12 and that the password is correct. Run echo "$CSC_LINK" | base64 --decode | openssl pkcs12 -info -passin pass:"$CSC_KEY_PASSWORD" locally to verify.

Windows: certificate base64 too long
: Windows CI environments may truncate environment variables over 8192 characters. Re-export the .pfx without the full certificate chain included. See Code Signing.

Build fails with "Cannot find module"
: Native modules need to be rebuilt for the target Electron version. Ensure npm ci (not npm install) is used, and check that electron-rebuild or @electron/rebuild is configured if needed.

Related Pages Copy Chapter

• Code Signing — environment variables, certificate types
• macOS Notarization — notarization setup and troubleshooting
• Auto Update — configuring electron-updater with GitHub releases
• Multi Platform Build — building for other platforms using Docker

Glossary (`website/docs/glossary.md`) Copy Section

Glossary

Quick reference for terms used throughout the electron-builder documentation.

A Copy Chapter

Ad-hoc signing
: A macOS code signature that identifies the binary but isn't tied to an Apple developer identity. Used for local development on Apple Silicon. Set mac.sign.identity to "-" to request ad-hoc signing. Unlike a proper Developer ID signature, ad-hoc signatures are not trusted by Gatekeeper for distribution.

AppImage
: A self-contained Linux application format. A single executable file that runs on any Linux distribution without installation. Users download the file, mark it executable (chmod +x), and run it. One of the two default Linux targets for electron-builder (along with Snap). See AppImage.

AppX / MSIX
: Microsoft's modern app packaging format for the Windows Store and enterprise MDM deployment. electron-builder's appx target produces .appx files. Microsoft's newer .msix format is functionally similar. See AppX.

ASAR
: Atom Shell ARchive — Electron's archive format for bundling application source files. Similar to a tar file but optimized for random access. Files inside ASAR are read through Electron's virtual filesystem. Native modules (.node files) must be excluded via asar.unpack.

asar.unpack
: A configuration option listing glob patterns for files that should be placed in app.asar.unpacked/ rather than inside the ASAR archive. Required for native modules and large binaries that need direct filesystem access.

C Copy Chapter

CA (Certificate Authority)
: An organization that issues and vouches for digital certificates. For Windows code signing, any major CA (DigiCert, Sectigo, SSL.com) works. For macOS, only Apple-issued certificates are recognized by Gatekeeper.

CFBundleIdentifier
: The unique reverse-DNS identifier for a macOS application bundle (e.g., com.company.myapp). Set via appId in electron-builder config. Must be unique across all apps on a user's machine and within the App Store.

CSC (Code Signing Certificate)
: The prefix for environment variables that provide code signing credentials to electron-builder (CSC_LINK, CSC_KEY_PASSWORD, etc.). See Code Signing.

D Copy Chapter

DMG
: Disk iMaGe — the standard macOS distribution format. A virtual disk that mounts when double-clicked, showing the app icon and an Applications shortcut for drag-and-drop installation. See DMG.

Developer ID
: An Apple code signing certificate type for apps distributed outside the Mac App Store. Comes in two forms: "Developer ID Application" (for signing app bundles) and "Developer ID Installer" (for signing PKG installers). Both require Apple Developer Program membership.

E Copy Chapter

Entitlements
: macOS security declarations that grant your app specific capabilities. Required when Hardened Runtime is enabled. Stored in .plist XML files referenced by mac.sign.entitlements and mac.sign.entitlementsInherit. Examples: com.apple.security.cs.allow-jit (required by Electron), com.apple.security.network.client (outbound networking).

EV Certificate (Extended Validation)
: A Windows code signing certificate with higher trust than standard OV certificates. EV certificates are physically bound to a USB security key and cannot be exported — which makes them incompatible with most CI/CD systems. Since 2024, SmartScreen no longer treats EV-signed installers differently from OV-signed ones; both build reputation over time.

F Copy Chapter

Flatpak
: A Linux packaging system that runs apps in a sandbox with controlled system access. Apps declare required permissions via "finish args." electron-builder produces single-file Flatpak bundles (not Flathub repository packages). See Flatpak.

FPM (Effing Package Management)
: A command-line tool used internally by electron-builder to create DEB, RPM, Pacman, APK, FreeBSD, and P5P packages. You generally don't interact with it directly; use fpm passthrough options in your config for advanced cases.

Fuses
: Feature flags embedded in the Electron binary that control security-sensitive behaviors at build time. Unlike runtime flags, fuses cannot be changed after the app is packaged. See Adding Electron Fuses.

G Copy Chapter

Gatekeeper
: Apple's security system that checks apps for valid code signatures and (on macOS 10.15+) notarization before allowing them to run. An app without a valid Developer ID signature prompts a security warning or is blocked entirely.

GUID (Globally Unique Identifier)
: A 128-bit identifier used by Windows installers to track application identity across installs and upgrades. In NSIS, this is the guid option. In MSI, this is the upgradeCode. Critical: changing the GUID between releases breaks silent upgrades of existing installations.

H Copy Chapter

Hardened Runtime
: A macOS security mode (mac.sign.hardenedRuntime: true) that restricts what your app can do without explicit entitlement declarations. Required for notarization. It blocks JIT compilation, unsigned library loading, and other potentially dangerous operations unless granted via entitlements.

I Copy Chapter

IDP (Installer Data Package / P5P)
: Solaris IPS (Image Packaging System) package format. electron-builder's p5p target produces packages for Solaris and illumos-based distributions.

K Copy Chapter

Keychain
: macOS's system for storing credentials, certificates, and keys. electron-builder reads code signing certificates from the keychain. On CI, you create a temporary keychain, import the certificate, and unlock it before building.

M Copy Chapter

MAS (Mac App Store)
: Apple's app distribution platform for macOS. MAS apps are sandboxed and require entitlements for any system access. electron-builder's mas target builds for App Store submission; mas-dev builds for local testing with a development provisioning profile. See MAS.

N Copy Chapter

Notarization
: Apple's service that scans your app for malware and issues a cryptographic ticket confirming the scan. Required for distributing apps outside the Mac App Store on macOS 10.15+. electron-builder handles notarization automatically when mac.notarize: true. See Notarization.

NSIS (Nullsoft Scriptable Install System)
: The Windows installer framework used by electron-builder's nsis and nsis-web targets. Produces highly customizable .exe installers. The default Windows target. See NSIS.

O Copy Chapter

OV Certificate (Organization Validated)
: A standard Windows code signing certificate that requires organizational identity verification. Unlike EV certificates, OV certificates can be exported as .pfx files and used in CI/CD. SmartScreen trust builds gradually based on how many users have downloaded and run the installer.

P Copy Chapter

PKG
: macOS installer package format. Used when your app needs to install files outside /Applications, run pre/post-install scripts, or install system components like launch daemons. Requires a separate "Developer ID Installer" certificate. See PKG.

Portable
: A Windows build target that produces a single .exe file requiring no installation. The app runs directly without writing to the registry or creating Start menu entries. See the Windows targets section in NSIS.

Provisioning Profile
: A macOS/iOS file that ties a certificate, an App ID, and a set of entitlements together. Required for Mac App Store submissions (mas target). Obtained from the Apple Developer portal.

S Copy Chapter

Sandbox
: An isolation mechanism that restricts what an application can access. Flatpak and Snap use sandboxes on Linux. Mac App Store apps are sandboxed by Apple's App Sandbox framework. Sandboxed apps must declare all required permissions.

Signing Identity
: The name of a code signing certificate as it appears in the macOS Keychain (e.g., Developer ID Application: My Company (ABCDE12345)). Referenced by CSC_NAME or mac.sign.identity in electron-builder config.

SmartScreen
: Windows Defender's application reputation service. It warns users when they run unsigned apps or apps from publishers with low download reputation. Since 2024, no certificate type bypasses the reputation-building period; EV and OV certificates both require time.

Snap
: Canonical's Linux packaging format, primarily for Ubuntu. Snap apps run in a sandbox with declared "interface plugs" controlling system access. electron-builder's snap target produces Snap packages for Snap Store distribution. See Snap.

Squirrel
: A Windows auto-update framework. electron-builder's squirrel.windows target is a legacy option — new projects should use NSIS with electron-updater instead. See Squirrel.Windows.

Stapling
: Attaching a notarization ticket to an app bundle so that Gatekeeper can verify notarization offline (without contacting Apple's servers). electron-builder staples the ticket automatically after notarization completes.

U Copy Chapter

Universal Binary
: A macOS binary that contains both x64 (Intel) and arm64 (Apple Silicon) code. The OS selects the appropriate slice at launch. Build with --universal or arch: universal. Results in a ~2× larger download but runs natively on all modern Macs.

UpgradeCode
: A GUID in MSI packages that identifies the application across versions for upgrade and uninstall operations. Must remain constant across all versions. Changing the UpgradeCode breaks silent upgrades and leaves old versions orphaned on managed systems. See MSI.

W Copy Chapter

WiX (Windows Installer XML Toolset)
: The toolchain used by electron-builder internally to produce MSI packages. Provides advanced Windows installer features like component tracking, repair, and rollback. You can pass additional WiX arguments via msi.additionalWixArgs.

Linux (`website/docs/linux.md`) Copy Section

title: "Linux" Copy Chapter

{!./partials/_upgrading-from-v26.md!}

The top-level linux key contains a set of options instructing electron-builder on how it should build Linux targets. These options are applicable to any Linux target.

Linux Target Overview Copy Chapter

electron-builder supports a wide range of Linux package formats. Choose based on your target audience and distribution method:

The default targets are AppImage and Snap.

Common Linux Configuration Copy Chapter

Options set in the linux key apply to all Linux targets:

linux:
  target:
    - AppImage
    - deb
    - rpm
  category: Utility                  # freedesktop.org category
  synopsis: "A short description"    # one-line description
  description: "Full description"    # longer description
  maintainer: "Name <email>"         # package maintainer
  vendor: "My Company"               # package vendor
  mimeTypes:
    - application/x-myapp
  executableArgs:
    - --enable-features=WebContentsFocusOnResize

:::note[v27: launcher entrypoint]
Every Linux target (deb/rpm, AppImage, snap, flatpak) now launches through a generated <executableName>-launcher shell script rather than invoking the executable directly. executableArgs (and forceX11) are injected into that launcher, and the generated .desktop Exec key points at it (e.g. Exec=/opt/MyApp/MyApp-launcher %U) rather than inlining the args. This makes executableArgs apply consistently across all Linux targets. If you ship a custom .desktop override, an AppArmor/snap profile, or a MIME handler that hard-codes the Exec command, point it at the *-launcher script. See v27 Breaking Changes → Linux launcher entrypoint.
:::

Desktop File Customization Copy Chapter

All Linux targets include a .desktop file for application menu integration. Customize it via linux.desktop:

linux:
  desktop:
    entry:
      Name: My Application
      Comment: A fantastic application
      Categories: Office;Productivity
      Keywords: productivity;notes;organizer
      StartupWMClass: my-app       # helps window managers match window to icon
      Terminal: false
      Type: Application
    desktopActions:
      NewWindow:
        Name: New Window
        Exec: my-app --new-window
      NewFile:
        Name: New File
        Exec: my-app --new-file

Standard freedesktop.org category values include: AudioVideo, Audio, Video, Development, Education, Game, Graphics, Network, Office, Science, Settings, System, Utility.

Window Association (`desktopName`) Copy Chapter

Electron derives its app_id — which becomes the window's WM_CLASS — from the desktopName field in your root package.json. Desktop environments (GNOME, KDE, etc.) use WM_CLASS to match a running window to its .desktop entry for taskbar grouping, dock badges, and launcher highlighting.

Without desktopName set, this association can break: the fallback WM_CLASS may not match the installed .desktop filename, so the DE treats the running app as an unknown window.

To fix this, set desktopName in package.json:

{
  "desktopName": "com.example.MyApp"
}

electron-builder installs the .desktop file as ${desktopName}.desktop (here com.example.MyApp.desktop) and sets StartupWMClass=com.example.MyApp, both matching Electron's app_id. A trailing .desktop in desktopName is tolerated (stripped before the filename is composed), so configs written for earlier versions keep working. When desktopName is absent, the filename falls back to executableName.

:::note[Changed in v27]
The installed .desktop filename is now always derived from desktopName. The linux.syncDesktopName flag that previously gated this behaviour has been removed — see the v27 breaking changes.
:::

:::warning[desktopName is required for reliable window association]
If desktopName is absent, electron-builder will log a warning at build time. Without it, desktop environments on GNOME, KDE, and others may not correctly link the running application window to its launcher entry.
:::

See the freedesktop.org specification for all valid keys.

Icon Configuration Copy Chapter

Provide a directory of PNG icons named with their size:

linux:
  icon: build/icons/

Files must be named NxN.png (e.g., 256x256.png, 512x512.png). If not specified, electron-builder auto-generates Linux icons from the macOS .icns file (if present) or the Windows .ico file.

Recommended sizes: 16, 24, 32, 48, 64, 96, 128, 256, 512 pixels.

Debian Package (`deb`) Copy Chapter

The deb target creates a .deb package installable via apt on Debian, Ubuntu, Mint, and other Debian-based distributions.

deb:
  depends:
    - libgtk-3-0
    - libnotify4
    - libnss3
    - libxss1
    - libxtst6
    - xdg-utils
    - libatspi2.0-0
    - libuuid1
    - libsecret-1-0
  recommends:
    - libappindicator3-1    # system tray support
  packageCategory: utils
  priority: optional

Common depends packages for Electron apps:

• libgtk-3-0 — GTK3 (required)
• libnotify4 — desktop notifications
• libnss3 — NSS (Chromium networking)
• libxss1 — screen saver extension
• libxtst6 — X test extension
• xdg-utils — desktop integration utilities
• libatspi2.0-0 — accessibility
• libuuid1 — UUID support
• libsecret-1-0 — keychain/Secret Service

Priority values: required, important, standard, optional (use optional for most apps)

RPM Package (`rpm`) Copy Chapter

The rpm target creates a .rpm package for Fedora, RHEL, CentOS, openSUSE, and other RPM-based distributions.

rpm:
  depends:
    - libXScrnSaver
    - libnotify
    - libappindicator
    - nss
    - gtk3
  compression: xz     # gz | bzip2 | xz | lzo (default: xz)
  packageCategory: Applications/Internet

Common depends for Electron on RPM systems:

• gtk3 — GTK3
• libnotify — notifications
• libXScrnSaver — screen saver
• nss — networking

After-install/after-remove scripts:

rpm:
  afterInstall: build/scripts/after-install.sh
  afterRemove: build/scripts/after-remove.sh

:::note[v27: maintainer-script variable syntax]
electron-builder interpolates variables into maintainer scripts (afterInstall / afterRemove) using shell-style ${var}. The legacy EJS <%= var %> interpolation was removed in v27 — update any templated maintainer scripts to ${var}. See v27 Breaking Changes → Linux maintainer-script EJS syntax.
:::

Pacman Package (`pacman`) Copy Chapter

:::warning[Beta]
The pacman target is in beta. Test thoroughly before distributing.
:::

Creates a .pkg.tar.zst package for Arch Linux and Arch-based distributions (Manjaro, EndeavourOS, etc.):

pacman:
  depends:
    - gtk3
    - libnotify
    - nss
    - libxss
    - libxtst
    - xdg-utils
    - at-spi2-core
    - libsecret

Alpine APK Package (`apk`) Copy Chapter

Creates an .apk package for Alpine Linux, commonly used in Docker containers:

apk:
  depends:
    - gtk+3.0
    - libnotify
    - nss

:::note[musl libc]
Alpine uses musl libc rather than glibc. Electron bundles its own copy of glibc-dependent libraries, but some native modules may not be compatible with Alpine without recompilation.
:::

FreeBSD Package (`freebsd`) Copy Chapter

Creates a .pkg package (not to be confused with macOS PKG) for FreeBSD systems:

freebsd:
  depends:
    - gtk3
    - libnotify
    - nss

FPM Passthrough Options Copy Chapter

The DEB, RPM, Pacman, APK, FreeBSD, and P5P targets are built using FPM internally. Pass additional FPM command-line arguments:

deb:
  fpm:
    - "--deb-changelog=CHANGELOG.md"
    - "--deb-no-default-config-files"

AppArmor Profile (Ubuntu 24+) Copy Chapter

Ubuntu 24.04 introduced mandatory AppArmor profiles for application sandboxing. Specify a custom profile:

deb:
  appArmorProfile: build/apparmor-profile

Without a profile, the app may be restricted by Ubuntu's default profile. See the AppArmor documentation for profile syntax.

Base Linux Configuration Copy Chapter

{!./app-builder-lib.Interface.LinuxConfiguration.md!}

Debian Package Options Copy Chapter

The top-level deb key contains a set of options for Debian packages.

{!./app-builder-lib.Interface.DebOptions.md!}

All LinuxTargetSpecificOptions can also be specified in deb to customize Debian packages.

`LinuxTargetSpecificOptions` — APK, FreeBSD, Pacman, P5P and RPM Options {#linuxtargetspecificoptions-apk-freebsd-pacman-p5p-and-rpm-options} Copy Chapter

The top-level apk, freebsd, pacman, p5p and rpm keys contain options for their respective Linux targets.

{!./app-builder-lib.Interface.LinuxTargetSpecificOptions.md!}

Mac (`website/docs/mac.md`) Copy Section

title: "macOS" Copy Chapter

{!./partials/_upgrading-from-v26.md!}

The top-level mac key contains a set of options instructing electron-builder on how it should build macOS targets. These options are applicable to any macOS target.

macOS Target Overview Copy Chapter

electron-builder supports several macOS distribution formats. Choose based on your distribution channel:

The default targets are zip and dmg (both are required for Squirrel.Mac auto-update).

Bundle ID Copy Chapter

The appId property sets the CFBundleIdentifier for your macOS app. This is a critical identifier — set it explicitly:

appId: "com.mycompany.myapp"

• Use reverse-DNS format: com.yourcompany.appname
• Must be unique in the Mac App Store if you intend to submit there
• Changing it after first release will break existing user data paths (NSUserDefaults, sandboxed containers, etc.)

Architecture Support Copy Chapter

electron-builder supports building for multiple CPU architectures:

Universal Binaries Copy Section

A universal binary runs natively on both Intel and Apple Silicon Macs with no performance penalty:

mac:
  target:
    - target: dmg
      arch: universal

Universal binary options:

• mergeASARs — merge x64 and arm64 ASAR archives into a single universal ASAR (true by default). Disable only if you have architecture-specific native modules that cannot be fat-binary merged.
• singleArchFiles — glob pattern for files that are single-arch and should NOT be merged (e.g., pre-built native binaries distributed only for one arch).
• x64ArchFiles — glob pattern for files that are x64-only. These are kept as x64 in the universal binary rather than being fat-binary merged.

In v27 these options live under mac.universal (a pass-through to @electron/universal) and only take effect when the target arch is universal:

mac:
  universal:
    mergeASARs: true
    singleArchFiles: "**/*.node"   # keep native modules as separate arch files

Recommended: Build Per-Arch on Correct Hardware Copy Section

While cross-compilation is possible, the most reliable approach is to build arm64 on Apple Silicon and x64 on Intel (or use a matrix in CI). Universal builds work best when both arches are produced natively and then merged.

Code Signing Copy Chapter

macOS apps must be signed to avoid Gatekeeper warnings. See Code Signing for full setup.

:::note[v27: signing options moved under mac.sign]
In v27 every macOS signing option (identity, entitlements, hardenedRuntime, type, provisioningProfile, binaries, requirements, timestamp, …) lives inside a single mac.sign object (sign.identity, sign.hardenedRuntime, …); signIgnore is now sign.ignore. electron-builder migrate-schema rewrites the old flat keys automatically. The same structure applies to mas and masDev. See v27 Breaking Changes → macOS signing.
:::

Certificate Identity Copy Section

Use mac.sign.identity to specify the signing certificate by name:

mac:
  sign:
    identity: "Developer ID Application: My Company (TEAM1234AB)"

Or use environment variables — the recommended approach for CI:

export CSC_LINK=/path/to/certificate.p12
export CSC_KEY_PASSWORD=yourpassword

Set mac.sign.identity: null (or mac.sign: null) to skip signing entirely. Set mac.sign.identity: "-" to use an ad-hoc signature (app will only run on the machine that built it).

:::warning[Ad-hoc signing and Hardened Runtime]
If you disable code signing, you should also disable Hardened Runtime (mac.sign.hardenedRuntime: false), as the combination of no signing and enabled Hardened Runtime may prevent the app from launching.
:::

Hardened Runtime Copy Section

mac.sign.hardenedRuntime is required for notarization on macOS 10.15+. It restricts what the app can do — you may need entitlements to allow capabilities. The default is true for standard darwin builds and false for Mac App Store builds (mas / mas-dev).

Entitlements Copy Chapter

You usually do not need to write an entitlements file at all. The defaults are already minimal and correct for a stock Electron app:

Nested binaries do not inherit the app's entitlements. They are handed to @electron/osx-sign, which picks a per-file default modelled on Chromium's own entitlements: the looser exceptions go only to the plugin helper that actually needs them, and every other nested file (frameworks, .node modules, executables in app.asar.unpacked) receives default.darwin.plist — allow-jit plus com.apple.security.device.{audio-input,bluetooth,camera,print,usb} and com.apple.security.personal-information.{location,photos-library}. Outside the plugin helper, none of these defaults grant disable-library-validation or allow-unsigned-executable-memory.

:::warning[Changed in v27]
Earlier versions applied a single entitlements file to the app and every nested binary, granting com.apple.security.cs.allow-unsigned-executable-memory and com.apple.security.cs.disable-library-validation to every process. Modern Electron does not need either in the main process, and both materially weaken the Hardened Runtime, so they are no longer granted by default. If your app depends on them, add them to your own build/entitlements.mac.plist (and build/entitlements.mac.inherit.plist for nested binaries) — see Loading third-party or unsigned binaries below.
:::

Supplying your own entitlements Copy Section

Create build/entitlements.mac.plist to override the app-level defaults:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  
  <key>com.apple.security.cs.allow-jit</key>
  <true/>
  
  
  
</dict>
</plist>

Your file replaces the default rather than extending it, so remember to keep com.apple.security.cs.allow-jit.

A custom build/entitlements.mac.plist applies to the app bundle only — nested binaries keep the per-file defaults described above and do not pick up your custom keys. The inherit plist is for entitlements a nested process needs for itself — for example disable-library-validation on a sidecar executable in app.asar.unpacked that loads third-party libraries of its own, or on a helper process that loads native modules. In that case add build/entitlements.mac.inherit.plist (or set mac.sign.entitlementsInherit). Doing so applies one plist to every nested binary and gives up the per-file defaults, so prefer leaving it absent unless you need it.

Loading third-party or unsigned binaries Copy Section

com.apple.security.cs.disable-library-validation turns off macOS library validation for the whole process. Grant it only when your app loads a framework, plugin, or native module signed by a different Team ID (or not signed at all) — for example a sidecar binary downloaded at runtime, or one excluded from signing via mac.sign.ignore.

Library validation is enforced by the process that loads the code, based on that process's own entitlements; what the library itself was signed with does not matter. A native module loaded by the main process therefore needs the key in build/entitlements.mac.plist; one loaded by a helper process (a utilityProcess, or a renderer with nodeIntegration) needs it in build/entitlements.mac.inherit.plist as well. The post-sign check below is skipped when the app entitlements grant it, because the main process is the usual loader.

After signing, electron-builder inspects the Mach-O libraries and bundles in app.asar.unpacked and Contents/PlugIns (which electron-builder never re-signs) and warns if any of them carry a foreign or missing signature while the entitlement is absent, so you find out at build time rather than from a launch crash. Executables (such as a bundled ffmpeg) are spawned rather than loaded, so they are not subject to library validation and are not flagged.

Ad-hoc builds (mac.sign.identity: "-") are handled automatically: an ad-hoc signature carries no Team ID, so electron-builder applies a built-in ad-hoc entitlements file that includes disable-library-validation for the app and its nested binaries.

electron-builder auto-detects build/entitlements.mac.plist and build/entitlements.mac.inherit.plist when present. To point at custom paths, set them under mac.sign:

mac:
  sign:
    entitlements: build/entitlements.mac.plist
    entitlementsInherit: build/entitlements.mac.inherit.plist

Common entitlements for Electron apps:

:::info[Entitlements and Notarization]
Notarization requires Hardened Runtime + appropriate entitlements. See Notarization for the complete notarization workflow.
:::

Info.plist Customization Copy Chapter

Inject arbitrary Info.plist keys using extendInfo:

mac:
  extendInfo:
    NSMicrophoneUsageDescription: "This app uses the microphone for..."
    NSCameraUsageDescription: "This app uses the camera for..."
    LSMultipleInstancesProhibited: true
    CFBundleURLTypes:
      - CFBundleURLSchemes:
          - myapp
        CFBundleURLName: "com.mycompany.myapp"

Helper Bundle IDs Copy Chapter

Electron spawns several helper processes, each with its own bundle ID. electron-builder sets these automatically based on your appId, but you can override them:

You only need to override these if you have a specific naming requirement (e.g., for provisioning profiles that enumerate each helper ID explicitly).

Other Common Options Copy Chapter

Dark mode: Set darkModeSupport: true if your app supports the system dark mode. This adds the NSRequiresAquaSystemAppearance: false key to Info.plist.

Minimum system version: minimumSystemVersion sets the LSMinimumSystemVersion in Info.plist. Electron itself has a minimum macOS version requirement — don't set this lower than Electron's requirement.

Signing additional binaries: Use mac.sign.binaries to list paths to additional native binaries within your app bundle that need to be signed (e.g., embedded CLIs, helper tools).

mac:
  sign:
    binaries:
      - Contents/MacOS/my-native-helper
      - Contents/Frameworks/MyFramework.framework/Versions/A/MyFramework

Product / executable name validation: As of v27, electron-builder rejects a productName or executableName that would require filename sanitization (so the generated <Name> Helper.app bundles stay consistent with CFBundleName and Electron's helper discovery). If a build fails with an "is not a valid macOS app bundle name" error, choose a name that needs no sanitization.

Configuration Copy Chapter

{!./app-builder-lib.Interface.MacConfiguration.md!}

Mas (`website/docs/mas.md`) Copy Section

title: "Mac App Store" Copy Chapter

{!./partials/_upgrading-from-v26.md!}

The top-level mas key contains a set of options instructing electron-builder on how it should build the MAS (Mac Application Store) target. Inherits all macOS options.

Use the mas-dev target (configured via the top-level masDev key) for local testing of MAS builds with a development provisioning profile.

MAS vs. Direct Distribution Copy Chapter

Prerequisites Copy Chapter

Certificates Copy Section

You need a Mac App Distribution certificate (for signing the app) and a Mac Installer Distribution certificate (for signing the PKG submitted to App Store Connect). Both are issued from your Apple Developer account.

:::tip
For local testing with mas-dev, you use a Development provisioning profile and a standard developer certificate, not the distribution ones.
:::

Provisioning Profile Copy Section

MAS apps require a provisioning profile that:

• Lists the specific entitlements your app uses
• Is tied to your App ID and certificate

Create provisioning profiles at developer.apple.com.

mas:
  sign:
    provisioningProfile: build/MyApp_AppStore.provisionprofile

:::note[v27: signing options are under mas.sign]
Like mac, all signing options on mas and masDev moved into a sign object in v27 (sign.provisioningProfile, sign.entitlements, sign.entitlementsInherit, …). electron-builder migrate-schema rewrites the old flat keys. See v27 Breaking Changes → macOS signing.
:::

App Sandbox Copy Section

All MAS apps must be sandboxed. Add to your entitlements (build/entitlements.mas.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  
  <key>com.apple.security.app-sandbox</key>
  <true/>
  
  <key>com.apple.security.cs.allow-jit</key>
  <true/>
  
  <key>com.apple.security.network.client</key>
  <true/>
</dict>
</plist>

And build/entitlements.mas.inherit.plist for helper processes:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.app-sandbox</key>
  <true/>
  <key>com.apple.security.inherit</key>
  <true/>
</dict>
</plist>

Point to these in your configuration:

mas:
  sign:
    entitlements: build/entitlements.mas.plist
    entitlementsInherit: build/entitlements.mas.inherit.plist
    provisioningProfile: build/MyApp_AppStore.provisionprofile

Common MAS Entitlements Copy Chapter

Testing with mas-dev Copy Chapter

The mas-dev target produces a build signed with a development certificate and development provisioning profile — suitable for testing sandbox behavior on your machine without going through App Store review.

masDev:
  sign:
    provisioningProfile: build/MyApp_Dev.provisionprofile
    entitlements: build/entitlements.mas.plist
    entitlementsInherit: build/entitlements.mas.inherit.plist

Build the dev target:

electron-builder --mac mas-dev

Building for the App Store Copy Chapter

electron-builder --mac mas

This produces:

• MyApp-<version>.pkg — the package to upload to App Store Connect

Submitting to App Store Connect Copy Chapter

1. Open App Store Connect
2. Create your app listing (if new) under My Apps → +
3. Use Transporter (free, from the Mac App Store) or xcrun altool / xcrun notarytool to upload the .pkg
4. The uploaded build appears in App Store Connect after processing (usually a few minutes)
5. Select the build for your release and submit for review

Common Review Rejection Reasons Copy Chapter

• Sandbox violations — the app attempts to access files or resources not permitted by entitlements
• Deprecated APIs — using APIs Apple has removed or flagged (check release notes)
• Missing privacy strings — if you access camera/mic/location, NSCameraUsageDescription etc. must be in Info.plist
• UI guidelines violations — buttons, windows, or flows that don't match Human Interface Guidelines
• Crash on launch — always test the MAS build on a clean machine before submitting

Configuration Copy Chapter

{!./app-builder-lib.Interface.MasConfiguration.md!}

Msi Wrapped (`website/docs/msi-wrapped.md`) Copy Section

title: "MSI Wrapped" Copy Chapter

The top-level msiWrapped key contains a set of options instructing electron-builder on how it should build Windows MSI-Wrapped packages.

What is MSI-Wrapped? Copy Chapter

MSI-Wrapped is a hybrid approach that combines the customizability of NSIS with the enterprise deployment compatibility of MSI. It works by:

1. Building your normal NSIS installer
2. Wrapping the NSIS .exe inside a minimal MSI package
3. The MSI acts as a thin shell that executes the NSIS installer when deployed

This allows enterprise IT teams to deploy the package through MSI-compatible tools (Group Policy, SCCM, Intune) while you retain all of NSIS's powerful customization capabilities for the actual installation experience.

MSI-Wrapped vs. Native MSI Copy Chapter

When to Use MSI-Wrapped Copy Chapter

Choose MSI-Wrapped when:

• You already have a well-configured NSIS installer and need to deploy it via Group Policy or MDM
• Your enterprise customers require MSI format but you don't want to maintain a separate MSI configuration
• You need NSIS-level UI customization combined with MSI deployment

Choose native MSI when:

• You need full MSI capabilities (custom actions, rollback, MSI database manipulation)
• You're targeting Windows Store / MSIX conversion
• You need clean per-machine/per-user support without NSIS

Configuration Copy Chapter

Wrapped Installer Arguments Copy Section

Pass additional command-line arguments to the wrapped NSIS installer when it is executed:

msiWrapped:
  wrappedInstallerArgs: "/S /D=C:\\MyApp"

Impersonation Copy Section

msiWrapped:
  impersonate: false    # Default: false

When impersonate: true, the MSI wrapper executes the NSIS installer under the user's identity rather than the system/SYSTEM account. This is useful for per-user installations that need to access user-specific resources.

Upgrade Code Copy Section

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

:::warning[Critical: Do Not Change After First Release]
See the MSI upgrade code warning — the same applies here.
:::

Complete Example Copy Chapter

win:
  target:
    - nsis
    - msi-wrapped

nsis:
  oneClick: false
  perMachine: true
  allowToChangeInstallationDirectory: true

msiWrapped:
  upgradeCode: "{A1234567-BCDE-F012-3456-789ABCDEF012}"
  impersonate: false
  wrappedInstallerArgs: "/SILENT"

Configuration Copy Chapter

{!./app-builder-lib.Interface.MsiWrappedOptions.md!}

Msi (`website/docs/msi.md`) Copy Section

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 Copy Chapter

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 Copy Chapter

Upgrade Code Copy Chapter

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.

:::warning[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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

{!./app-builder-lib.Interface.MsiOptions.md!}

Msix (`website/docs/msix.md`) Copy Section

The top-level msix key contains a set of options instructing electron-builder on how it should build MSIX packages for the Microsoft Store, enterprise sideloading, and modern Windows deployment.

:::info[Beta]
The MSIX target is beta. The configuration surface and generated manifest are still evolving. Pin your electron-builder version and re-test packaging after upgrades.
:::

All options are optional. All required MSIX configuration is inferred and computed automatically from your application metadata.

MSIX vs. AppX Copy Chapter

MSIX is the modern successor to AppX. They share the same underlying manifest format (AppxManifest.xml), the same packaging tool (makeappx.exe), and the same signing requirements, but MSIX exposes newer manifest schemas and deployment features that AppX does not.

If you are starting fresh, prefer MSIX. AppX remains for backward compatibility.

When to Use MSIX Copy Chapter

Choose MSIX when:

• Windows Store distribution — your app will be listed in the Microsoft Store.
• Enterprise sideloading — IT manages app distribution via MDM/Intune without the Store.
• Windows 10S / Windows SE — these locked-down editions only run Store-packaged apps.
• You need modern packaging features — package integrity, bundled architectures, or registered Windows services.

For standard consumer distribution with self-managed auto-updates, NSIS is simpler. For enterprise deployment without the Store, MSI is often preferred.

Requirements Copy Chapter

MSIX packaging requires a modern Windows Kits toolset that bundles makeappx.exe, makepri.exe, and the MSIX-capable Windows SDK. Set toolsets.winCodeSign to any modern bundle >= 1.0.0 (e.g. 1.0.0, 1.1.0, or 1.3.0):

toolsets:
  winCodeSign: "1.1.0"
win:
  target: msix

:::warning
The legacy winCodeSign-2.6.0 bundle (toolset 0.0.0) does not include the SDK version required for MSIX. Building MSIX without a modern toolset throws an InvalidConfigurationError.
:::

MSIX can be built on:

• Windows 10 / Windows Server 2012 R2 (version 6.3+) or later — native.
• macOS via Parallels Desktop — electron-builder drives a Windows VM through Parallels to run the Windows-only packaging tools. See Building on macOS below.

Linux is not supported for MSIX.

Quick Start Copy Chapter

win:
  target: msix
toolsets:
  winCodeSign: "1.1.0"
msix:
  identityName: "MyCompany.MyApp"
  publisher: "CN=My Company, O=My Company, C=US"
  publisherDisplayName: "My Company"
  displayName: "My Application"

electron-builder --win msix

MSIX Assets Copy Chapter

MSIX uses the same logo/icon assets as AppX. Place them in the appx folder inside your build resources directory (default: build/appx/):

Default assets are substituted for the required logos if you don't provide your own. Scale variants (e.g., Square44x44Logo.scale-200.png, BadgeLogo.targetsize-48.png) are supported — when any scaled asset is present, electron-builder runs makepri.exe to generate resources.pri automatically. See Microsoft's tile asset guidelines.

Identity and Publisher Copy Chapter

msix:
  applicationId: "MyApp"                            # alpha-numeric segments separated by periods, each segment starting with a letter
  identityName: "MyCompany.MyApp"                   # unique within the Store; 3–50 chars, [a-zA-Z0-9.-]
  publisher: "CN=My Company, O=My Company, C=US"    # must match certificate Subject exactly
  publisherDisplayName: "My Company"                # friendly publisher name shown to users
  displayName: "My Application"                     # shown in Start menu / Store

Defaults when omitted:

• applicationId → derived from identityName (a leading numeric prefix such as 01234 is stripped automatically, with a warning), falling back to the application name. Validated to 1–64 characters.
• identityName → the application name. Validated to 3–50 characters of [a-zA-Z0-9.-].
• publisherDisplayName → company name from your application metadata (author in package.json). Building fails if neither is set.

:::warning[Publisher Must Match Certificate]
The publisher value must exactly match the Subject field of your code signing certificate. Mismatches cause installation failures. When building for the Store (no certificate configured), electron-builder uses CN=ms as a placeholder — the Store re-signs on submission.
:::

Capabilities Copy Chapter

MSIX apps declare the system capabilities they use:

msix:
  capabilities:
    - runFullTrust                  # required for Electron apps — always included
    - internetClient                # outbound internet access
    - privateNetworkClientServer    # local network
    - webcam                        # camera access
    - microphone                    # microphone access

runFullTrust is required for Electron apps and is always added, even if you specify a different set — you cannot remove it. Invalid capability names cause the build to fail with invalid windows capabilities. The full list is in Microsoft's capability documentation.

Tile Customization Copy Chapter

msix:
  backgroundColor: "#2c2c2c"    # tile background color (CSS color). Default: #464646
  showNameOnTiles: false        # overlay app name on the wide & square tiles. Default: false

Optional tile assets enable extra visual elements automatically when present in build/appx/: BadgeLogo.png (lock-screen badge), LargeTile.png (310×310), SmallTile.png (71×71), and SplashScreen.png.

Language Support Copy Chapter

msix:
  languages:
    - en-US     # first entry is the default language
    - de-DE
    - fr-FR
    - ja-JP

Declares which languages your app supports for Store listings and localized resources. Defaults to ["en-US"]. Underscores are normalized to hyphens (en_US → en-US).

Version Targeting Copy Chapter

msix:
  minVersion: "10.0.17763.0"        # Windows 10 1809 minimum (Store minimum). This is the default.
  maxVersionTested: "10.0.22621.0"  # defaults to minVersion when omitted

These map to MinVersion / MaxVersionTested on <TargetDeviceFamily Name="Windows.Desktop" />.

msix:
  setBuildNumber: false   # include the build number in the package version. Default: false

Package Integrity Copy Chapter

msix:
  enforcePackageIntegrity: true   # Default: false

When enabled, emits inside. The child `` element is what actually turns on runtime integrity checks — a bare/childless element is a no-op. Windows then verifies that no package files have been tampered with after signing. Requires Windows 10 version 2004 (build 19041) or later.

Windows Services Copy Chapter

Register Windows Services that ship inside the package (desktop6 schema). Requires Windows 10 version 1903 (build 18362) or later, and the packagedServices (or localSystemServices) restricted capability declared via capabilities — services will not register without it.

msix:
  capabilities:
    - packagedServices                 # restricted capability — required for windows.service
  windowsServices:
    - name: "MyBackgroundService"        # required — Service Control Manager name
      executable: "app/service.exe"      # optional — defaults to the main app executable
      startupType: "auto"                # auto | manual | disabled. Default: manual
      startAccount: "localSystem"        # localSystem | localService | networkService. Default: localSystem
      arguments: "--mode service"        # optional — command-line arguments

Each entry produces a <desktop6:Extension Category="windows.service" Executable="..." EntryPoint="Windows.FullTrustApplication"><desktop6:Service Name="..." StartupType="..." StartAccount="..." Arguments="..." /></desktop6:Extension> declaration.

Auto-Launch Extension Copy Chapter

msix:
  addAutoLaunchExtension: true

When true, adds a desktop:Extension Category="windows.startupTask" so the app runs on user login. When unset, it defaults to true only if electron-winstore-auto-launch is present in your dependencies, otherwise false. Requires the runFullTrust capability (always present).

Protocols and File Associations Copy Chapter

MSIX picks up the top-level protocols and fileAssociations configuration and emits the corresponding uap:Extension declarations — you do not configure these under msix:

protocols:
  name: "My App Protocol"
  schemes: ["myapp"]
fileAssociations:
  - ext: "myext"
    name: "My Custom File"

Custom Manifest and Extensions Copy Chapter

For advanced scenarios, supply your own manifest template or inject extra XML:

msix:
  customManifestPath: "msix/AppxManifest.xml"     # relative to build resources
  customExtensionsPath: "msix/extensions.xml"     # injected into <Extensions>

The custom manifest supports the same ${} macros as the default template, including the MSIX-specific macro ${packageIntegrity}. Windows services are injected via the ${extensions} macro alongside protocol/file-association extensions.

Note the two paths resolve against different base directories: customManifestPath is relative to the build resources directory, whereas customExtensionsPath is resolved relative to the app source directory (the packaged app dir), not the build resources directory.

:::warning[Namespaces in a custom template]
If you supply your own template, it must declare the namespaces used by the features you enable — desktop (auto-launch startup task), uap (protocols / file associations), uap10 (package integrity), and desktop6 (services) — and list the appropriate prefixes in IgnorableNamespaces. Omitting them produces an invalid manifest. Start from the default template above.
:::

Bundles and Store Uploads Copy Chapter

When you build more than one architecture, electron-builder can combine the per-architecture .msix packages into a single .msixbundle, and optionally wrap it into a .msixupload archive for the Microsoft Store Partner Center:

win:
  target:
    - target: msix
      arch:
        - x64
        - arm64
msix:
  createMsixbundle: true     # combine architectures into one .msixbundle. Default: true (when >1 arch)
  createMsixupload: true     # produce a .msixupload for Partner Center submission. Default: false

• A .msixbundle is produced only when more than one architecture is built and createMsixbundle is not false.
• A .msixupload is a plain ZIP of the bundle (or, if no bundle was produced, the single package). It is not code-signed — the Store re-signs on submission.

:::note
If you set createMsixbundle: false while building multiple architectures and request createMsixupload: true, the upload will contain only the first architecture's package. Keep createMsixbundle enabled for multi-architecture Store submissions.
:::

Code Signing {#msix-package-code-signing} Copy Chapter

MSIX artifacts (.msix, .msixbundle) are signed with SHA-256 (single signature; dual SHA-1/SHA-256 signing does not apply to MSIX).

• Store distribution — no manual signing needed. The Store signs the package with a Microsoft certificate during submission; the publisher is replaced with a Store-managed identity.
• Sideloading / enterprise — the package must be signed with a trusted certificate whose Subject matches publisher. See Windows Code Signing.

For self-signed certificates during development, see Microsoft's certificate guide.

Building on macOS Copy Chapter

MSIX packaging tools are Windows-only. On macOS, electron-builder runs them inside a Windows VM via Parallels Desktop. Temp files are routed through your home directory so the VM can access them over the always-available \\Mac\Home share. Ensure a Parallels Windows VM is configured and the modern winCodeSign toolset is available inside it.

Testing Locally Copy Chapter

# Install locally (Developer Mode must be enabled for unsigned packages, or import the signing cert first)
Add-AppxPackage -Path ".\MyApp-1.0.0.msix"

# Install a bundle
Add-AppxPackage -Path ".\MyApp-1.0.0.msixbundle"

# Verify it is registered
Get-AppxPackage | Where-Object { $_.Name -like "*MyApp*" }

# Inspect the installed manifest
$p = Get-AppxPackage | Where-Object { $_.Name -like "*MyApp*" } | Select-Object -First 1
(Get-AppxPackageManifest -Package $p.PackageFullName).OuterXml

# Uninstall
Get-AppxPackage | Where-Object { $_.Name -like "*MyApp*" } | Remove-AppxPackage

To install a package signed with a self-signed certificate, first import that certificate into Trusted People on the target machine — see Microsoft's signing guide.

Publishing to the Microsoft Store Copy Chapter

1. Create a Microsoft Developer account and reserve your app name in Partner Center.
2. Build with createMsixupload: true to produce a .msixupload.
3. Upload the .msixupload via the Partner Center submission flow.
4. Complete the submission (age rating, pricing, screenshots) and wait for certification.

Auto-Updates Copy Chapter

MSIX auto-updates are handled by the Microsoft Store (or your App Installer .appinstaller flow), not by electron-updater. For self-managed auto-updates outside the Store, use NSIS instead.

Common Questions Copy Chapter

Which toolset version do I need? toolsets.winCodeSign can be any modern bundle >= 1.0.0 (e.g. 1.0.0, 1.1.0, or 1.3.0). Only an unset toolset or the legacy 0.0.0 bundle (winCodeSign-2.6.0, which lacks the required SDK) is rejected.

Can I build MSIX on Linux? No. Use Windows, or macOS with Parallels Desktop.

Why is my multi-arch .msixbundle named with one architecture? Bundle and upload artifacts span all built architectures; a custom artifactName containing ${arch} will still render a single architecture token. Prefer an artifactName without ${arch} for bundles.

Does MSIX support auto-update via electron-updater? No — see Auto-Updates above.

Configuration Copy Chapter

{!./app-builder-lib.Interface.MsixOptions.md!}

Notarization (`website/docs/notarization.md`) Copy Section

macOS Notarization

Notarization is Apple's security service that scans your app for malicious software before distribution. Starting with macOS 10.15 (Catalina), apps distributed outside the Mac App Store must be notarized or Gatekeeper will block them.

Notarization vs. Code Signing Copy Chapter

These are two separate steps, both required:

electron-builder handles all three steps automatically when configured.

Prerequisites Copy Chapter

Before notarizing, you need:

1. An active Apple Developer Program membership ($99/year)
2. A Developer ID Application certificate (not Mac App Store)
3. Hardened Runtime enabled in your build configuration
4. Required entitlements set (see below)
5. Authentication credentials (Apple ID + app-specific password, or API key)

Enabling Notarization Copy Chapter

mac:
  notarize: true
  sign:
    hardenedRuntime: true
    entitlements: build/entitlements.mac.plist
    entitlementsInherit: build/entitlements.mac.inherit.plist

:::note[v27]
notarize stays on mac, but the signing options (hardenedRuntime, entitlements, entitlementsInherit) moved under mac.sign in v27. See macOS signing.
:::

Authentication — Option A: Apple ID Copy Section

Create an app-specific password at appleid.apple.com (do not use your Apple ID password directly).

Set these environment variables:

[email protected]
APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
APPLE_TEAM_ID=ABCDE12345

Authentication — Option B: App Store Connect API Key (Recommended for CI) Copy Section

API keys don't expire and don't require two-factor authentication, making them ideal for CI.

1. Go to App Store Connect → Users and Access → Keys
2. Create a new key with "Developer" role
3. Download the .p8 file (only downloadable once)
4. Note the Key ID and Issuer ID

Then set the following environment variables:

# base64-encode the .p8 file for use as a CI secret
APPLE_API_KEY=<base64-encoded-p8-content>
APPLE_API_KEY_ID=KEYID
APPLE_API_ISSUER=your-issuer-id
APPLE_TEAM_ID=ABCDE12345

Authentication — Option C: Keychain Profile (stored credentials) Copy Section

If you have previously stored notarization credentials via xcrun notarytool store-credentials, reference them by profile name:

APPLE_KEYCHAIN_PROFILE=my-notarization-profile
APPLE_KEYCHAIN=/path/to/keychain.keychain-db  # optional; defaults to system keychain

This approach requires credentials to be pre-stored on the build machine and is not suitable for ephemeral CI environments.

Hardened Runtime Requirements Copy Chapter

Notarization requires Hardened Runtime (mac.sign.hardenedRuntime: true). This restricts what your app process can do unless you explicitly declare entitlements.

Modern Electron needs exactly one exception, and electron-builder grants it by default — no entitlements file is required to notarize a stock Electron app:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.cs.allow-jit</key>
  <true/>
</dict>
</plist>

Write that to build/entitlements.mac.plist only if you need to add capabilities of your own; your file replaces the default rather than extending it, so keep com.apple.security.cs.allow-jit in it.

Do not add com.apple.security.cs.allow-unsigned-executable-memory out of habit. It was needed by Electron versions from the 2019 era, is not needed by modern V8/Electron, and weakens the Hardened Runtime for no benefit.

Leave build/entitlements.mac.inherit.plist absent unless you truly need it. Without it, each nested binary is signed with @electron/osx-sign's per-file defaults, which mirror Chromium's own entitlements — renderer and GPU helpers get only allow-jit, and the looser exceptions go to the plugin helper alone. Supplying the file applies one plist to every nested binary instead.

Common Entitlements Copy Section

Notarization in GitHub Actions Copy Chapter

jobs:
  build-mac:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build, sign, and notarize
        run: npx electron-builder --mac
        env:
          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Required GitHub Secrets Copy Section

How Stapling Works Copy Chapter

After notarization, Apple returns a "ticket" that confirms your app was approved. electron-builder automatically staples this ticket to the app bundle — meaning the notarization check can succeed even without an internet connection.

Stapling is performed automatically when notarize: true. You don't need to configure anything extra.

Testing Notarization Copy Chapter

After building, verify the notarization status:

# Check Gatekeeper assessment (simulates what macOS does on first launch)
spctl --assess --verbose --type exec dist/mac/MyApp.app

# Should output:
# dist/mac/MyApp.app: accepted
# source=Notarized Developer ID

# Check that the stapling ticket is attached
xcrun stapler validate dist/mac/MyApp.app
# Should output: The validate action worked!

# Check code signature
codesign --verify --deep --strict --verbose=2 dist/mac/MyApp.app

Troubleshooting Copy Chapter

"The software certificate used to sign this application is not trusted on this machine"
: Your Developer ID certificate is not in the system keychain or hasn't been trusted. Verify CSC_LINK points to a valid Developer ID certificate — electron-builder imports and configures the certificate automatically.

Notarization hangs indefinitely
: Apple's notarization service may be slow. electron-builder polls for completion. If it consistently times out, check your network connection and Apple's developer system status.

"Package Invalid: the binary is not signed with a valid Developer ID certificate"
: You used a Mac App Store certificate for direct distribution, or vice versa. Direct distribution requires a "Developer ID Application" certificate, not "Apple Distribution."

"App can't be opened because Apple cannot check it for malicious software"
: Notarization succeeded but the app wasn't stapled, or the user opened the app before stapling completed. Run xcrun stapler validate to check. Rebuild with electron-builder to get a properly stapled app.

"com.apple.security.cs.allow-jit entitlement required"
: Add the JIT entitlement to your entitlements.mac.plist. See the entitlements section above.

Notarization rejected: "The executable does not have the Hardened Runtime enabled"
: Set mac.sign.hardenedRuntime: true in your mac configuration.

"Invalid Info.plist (plist or signature have wrong format)"
: All binaries inside the app bundle must be signed. This often happens with third-party native modules or bundled binaries. Ensure asar.unpack is set for any .node files and that all binaries are signed before creating the final distributable. Use a custom afterSign hook if you need to sign additional binaries.

Related Pages Copy Chapter

• macOS Code Signing — exporting certificates, keychain management, disabling signing
• Code Signing Overview — environment variables, CI setup, certificate types
• macOS Configuration — entitlements, Hardened Runtime, bundle ID setup
• GitHub Actions — full workflow examples

Nsis (`website/docs/nsis.md`) Copy Section

title: "NSIS" Copy Chapter

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 Copy Chapter

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.

:::note[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 Copy Chapter

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 a local package file using --package-file=path_to_file. It must be one of the packages built with the installer (any arch; checksum is checked).

The web installer verifies the package it installs against the SHA-512 of the packages built with it:

• A package passed via --package-file (electron-updater passes the package it verified against the update manifest) must match one of them, for any arch.
• A package downloaded from the default, publish-derived (versioned) URL must match the package for the detected arch.
• A package downloaded from an explicit appPackageUrl (e.g. a version-independent latest URL) is not verified, since that URL can serve packages of other builds.

A local package (passed via --package-file, or found next to the installer) is first copied into the installer's own temporary directory. The installer verifies and installs that copy. The local file itself is left in place; for an update, electron-updater removes the package it passed once the updated app starts. With allowUnverifiedAppPackage a package passed via --package-file is still copied, but not verified.

A mismatch, a --package-file package that cannot be copied, or a package that cannot be downloaded (also a download cancelled in the progress window) aborts the installation (exit code 2); a package next to the installer that doesn't match or cannot be copied is ignored and the package is downloaded instead. When a download fails, an interactive run first offers to retry, and a silent run (/S) aborts right away. The installer copies, verifies and, if needed, downloads the package before it removes an installed version, so an installation aborted for one of these reasons leaves that version in place. Because the download can take a while, a run that isn't an update (--updated) then checks again whether the app is running, with the same prompt as at the start (Cancel aborts with exit code 2), before the installed version is removed; a custom customCheckAppRunning macro is not run a second time. Set nsisWeb.allowUnverifiedAppPackage: true (default false) to skip the --package-file and versioned-download checksum checks (a package next to the installer is still checked) only if you intentionally use one web installer with packages of other builds (e.g. a version-independent installer with --package-file).

For auto-update, electron-updater installs web-installer updates only when disableWebInstaller is false; installs made by an nsis-web installer built with electron-builder v27+ default to false automatically — see Auto Update. Don't set updateManifest: false for nsis-web apps: signed update manifests cover the web package's path, SHA-512 and size.

Custom NSIS script Copy Chapter

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.
:::

For nsis-web, a custom script that copies installSection.nsh should insert !insertmacro prepareWebPackage before uninstallOldVersion; otherwise the package is prepared in installApplicationFiles, after the installed version is removed.

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.

:::warning[v27: file-association ProgID format changed]
NSIS installers now register each fileAssociations entry under a unique generated ProgID (.<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.

:::note[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

:::tip[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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

:::tip[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

:::

:::tip[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 Copy Chapter

{!./app-builder-lib.Interface.NsisOptions.md!}

Pkg (`website/docs/pkg.md`) Copy Section

The top-level pkg key contains a set of options instructing electron-builder on how it should build macOS PKG product archive installers.

When to Use PKG Copy Chapter

PKG (.pkg) files are macOS installer packages that run Apple's native Installer application. Use PKG when:

• System-level installs are required — installing launch daemons, kernel extensions (or System Extensions on modern macOS), or files outside /Applications
• Custom install scripts are needed — pre/postinstall shell scripts run with root privileges during installation
• Enterprise managed deployment — PKG integrates with MDM systems and software management tools like Munki, Jamf, and SCCM for macOS
• Installer UI customization — displaying welcome screens, license agreements, readme files, and conclusion pages

For standard consumer app distribution, DMG is the conventional choice. For Mac App Store distribution, see MAS.

Certificate Requirements Copy Chapter

Signing a PKG file requires a Developer ID Installer certificate — this is a different certificate from the Developer ID Application certificate used to sign the app bundle inside the PKG.

pkg:
  identity: "Developer ID Installer: My Company (TEAM1234AB)"

Or use the CSC_INSTALLER_LINK and CSC_INSTALLER_KEY_PASSWORD environment variables in CI.

:::tip
You can have both Developer ID Application and Developer ID Installer certificates. The application certificate signs the .app bundle, and the installer certificate signs the .pkg wrapper.
:::

:::note[v27: pkg.identity is not inherited]
As of v27 the .pkg installer identity resolves from pkg.identity (or CSC_INSTALLER_LINK) only — it no longer falls back to the app/mac-level signing identity (the old mac.identity fallback is gone, since that field moved to mac.sign.identity). If your .pkg relied on inheriting the mac-level identity, set pkg.identity explicitly.
:::

Installation Location Copy Chapter

By default the app is installed to /Applications. Override with installLocation:

pkg:
  installLocation: "/Applications"

Setting a non-standard install location (e.g., /usr/local/bin) is unusual for Electron apps but may be needed for CLI tools bundled with the app.

Install Scripts Copy Chapter

Place shell scripts in the scripts directory (default: build/pkg-scripts/). These run at install time with root privileges:

pkg:
  scripts: build/pkg-scripts   # default

Example postinstall script:

#!/bin/bash
# Register a launch daemon after install
launchctl load /Library/LaunchDaemons/com.mycompany.myapp.daemon.plist
exit 0

:::warning[Script Permissions]
Scripts must be executable (chmod +x). Scripts run as root during installation — test thoroughly. A failing script (non-zero exit code) will abort the installation.
:::

See the macOS Kernel Extensions tutorial for a detailed example.

Installer UI Customization Copy Chapter

Customize the pages displayed in Apple's Installer:

pkg:
  welcome: build/welcome.html    # or .rtf, .txt
  license: build/license.html    # or .rtf, .txt
  conclusion: build/conclusion.html

Supported file formats for each page: HTML, RTF, plain text.

Background image — displayed behind the installer pages (macOS 10.5+):

pkg:
  background:
    file: build/installer-background.png
    alignment: center       # center | left | right | top | bottom | topleft | topright | bottomleft | bottomright
    scaling: tofit          # tofit | proportional | none

Installation Behavior Options Copy Chapter

Control how the installer behaves when re-installing or upgrading:

For most apps, leave these at their defaults.

Forcing App Closure Before Install Copy Chapter

If your installer or upgrade requires the app to not be running:

pkg:
  mustClose:
    - com.mycompany.myapp
    - com.mycompany.myapp.helper

The Installer will prompt the user to quit any running processes with matching bundle IDs before proceeding.

Extra Component Packages Copy Chapter

Bundle additional .pkg files alongside the main component:

pkg:
  extraPkgsDir: build/extra-pkgs

All .pkg files in this directory will be included as additional components in the installer. Useful for installing additional software alongside your app (e.g., a CLI tool, a system extension).

Complete Example Copy Chapter

pkg:
  identity: "Developer ID Installer: My Company (TEAM1234AB)"
  installLocation: "/Applications"
  scripts: build/pkg-scripts
  welcome: build/welcome.html
  license: build/license.rtf
  conclusion: build/conclusion.html
  background:
    file: build/background.png
    alignment: center
    scaling: tofit
  mustClose:
    - com.mycompany.myapp
  isRelocatable: true
  overwriteAction: upgrade

Troubleshooting Copy Chapter

"The package is not signed" error: Ensure you have a valid Developer ID Installer certificate (not Application). Check the certificate identity string matches exactly.

Script fails silently: Run the PKG in verbose mode via Terminal: sudo installer -verbose -pkg YourApp.pkg -target /. Non-zero exit from a script aborts installation.

App not found after install: Verify installLocation is correct and the app bundle ends up at the expected path. Check Console.app for installer logs.

PKG won't overwrite existing version: The isVersionChecked: false option disables version checking, allowing downgrades.

Configuration Copy Chapter

{!./app-builder-lib.Interface.PkgOptions.md!}

Programmatic Usage (`website/docs/programmatic-usage.md`) Copy Section

title: "Programmatic Usage" Copy Chapter

:::note
Node.js >=22.12.0 required. electron-builder v27 ships as native ESM. CJS require() continues to work on Node >=22.12 via Node's stable require(esm) support.
:::

The example below uses ESM syntax (recommended). A CJS equivalent is shown at the bottom.

/* Detailed source-code truncated for AI context efficiency. */

CJS equivalent (Node >=22.12.0):

const { build, Platform } = require("electron-builder")

build({
  targets: Platform.MAC.createTarget(),
  config: { /* options */ },
})
  .then((result) => console.log(JSON.stringify(result)))
  .catch((error) => console.error(error))

Publish (`website/docs/publish.md`) Copy Section

{!./partials/_upgrading-from-v26.md!}

The publish key contains a set of options instructing electron-builder on how it should publish artifacts and build update info files for auto update.

String | Object | Array<Object | String> where Object it is Keygen, Generic Server, GitHub, S3, Spaces, R2 or Snap Store options. Order is important — first item will be used as a default auto-update server. Can be specified in the top-level configuration or any platform- (mac, linux, win) or target- (e.g. nsis) specific configuration.

Note that when using a generic server, you have to upload the built application and metadata files yourself.

Travis and AppVeyor support publishing artifacts. But it requires additional configuration for each CI and you need to configure what to publish.
electron-builder makes publishing dead simple.

!!! important "Publishing Must Be Explicitly Requested"
Publishing is not performed automatically. You must explicitly request publishing using the --publish CLI flag (e.g., --publish always, --publish onTag, --publish onTagOrDraft) or by setting the publish option in your configuration.

If GH_TOKEN or GITHUB_TOKEN is defined — defaults to [{provider: "github"}].

If KEYGEN_TOKEN is defined and GH_TOKEN or GITHUB_TOKEN is not — defaults to [{provider: "keygen"}].

If GITHUB_RELEASE_TOKEN is defined, it will be used instead of (GH_TOKEN or GITHUB_TOKEN) to publish your release.

• e.g. mac: export GITHUB_RELEASE_TOKEN=<my token>
• the GITHUB_TOKEN will still be used when your app checks for updates, etc.
• you could make your GITHUB_TOKEN "Read-only" when creating a fine-grained personal access token, and "Read and write" for the GITHUB_RELEASE_TOKEN.
• "Contents" fine-grained permission was sufficient. (at time of writing - Apr 2024)

:::warning[Implicit publishing was removed in v27]
In v26 and earlier, electron-builder auto-detected when to publish based on CI environment conditions (npm lifecycle event, a git tag in CI, etc.). As of v27 this implicit behavior is removed — publishing never happens unless you request it. This closes a hole where unfinished work or secrets could be published unintentionally.

Explicitly specify your publish intent with the --publish CLI flag (e.g. --publish always, --publish onTag, --publish onTagOrDraft, --publish never) or set the publish option in your configuration. See v27 Breaking Changes → implicit --publish removed.
:::

:::info[Snap store]
snap target by default publishes to the Snap Store (the app store for Linux). To force publishing to another provider, explicitly specify publish configuration for snap.
:::

You can publish to multiple providers. For example, to publish Windows artifacts to both GitHub and Bitbucket (order is important — first item will be used as a default auto-update server, so in this example the app will use GitHub as the auto-update provider):

{
  "build": {
    "win": {
      "publish": ["github", "bitbucket"]
    }
  }
}

win:
  publish:
      # an object provider for github with additional options
    - provider: github
      protocol: https
      # a string provider for bitbucket that will use default options
    - bitbucket

Which settings become the auto-update feed (`app-update.yml`) {#app-update-yml-feed} Copy Section

The auto-update feed an installed app polls is the first provider written to app-update.yml inside the packaged app. One packaged app (for example win-unpacked, linux-unpacked or the .app bundle) holds a single app-update.yml, shared by every target built from it. It is resolved like this:

1. The targets of that app that write update info — NSIS/NSIS web installer, AppX with electronUpdaterAware, macOS dmg/zip, AppImage, deb/rpm/pacman — each resolve their own publish: the target-level value (e.g. nsis.publish) first, then the platform level (win.publish), then the top level.
2. If one or more of them emit a manifest under those settings, their first provider that receives the manifest becomes the feed — a provider with publishAutoUpdate: false gets no latest*.yml, so it is skipped (with publish: [{ provider: "s3", …, publishAutoUpdate: false }, "github"] the feed is GitHub). They must agree: two such targets whose first providers differ (for example nsis.publish pointing at S3 while an AppX inherits win.publish: github, or dmg.publish differing from zip.publish) would leave some installs polling a feed that never receives their manifest. A publishing build then fails at build start with an InvalidConfigurationError; a build without a publish policy logs a warning that publishing will fail, and writes no app-update.yml for that app. Configure publish once at the platform level, or give the targets the same first provider (later providers may differ). Only what decides the feed is compared — the provider and options such as url, bucket, region, path, owner, repo or channel; options that only affect the upload (publishAutoUpdate, timeout, and for S3-compatible providers acl, storageClass, encryption) may differ.
3. If none of them emits a manifest — only non-updating targets such as snap or portable, or a target with publish: null or publishAutoUpdate: false on every provider — the platform/top-level publish is used, as before.
4. If no level configures publish at all, the feed falls back to GitHub when the repository field points there (see GitHub Repository).

For example, with only a target-level setting

nsis:
  publish:
    provider: s3
    bucket: my-updates

installed NSIS apps poll the S3 bucket and embed the update-manifest trust key. Before this rule, the target-level setting was not read for app-update.yml: such a build shipped no app-update.yml at all (no feed and no trusted key), or — with a GitHub repository — a GitHub feed while the manifests went to S3.

You can also configure publishing using CLI arguments, for example, to force publishing snap not to Snap Store, but to GitHub: -c.snap.publish=github

A custom publish provider can be used if needed.

:::tip[Macros]
In all publish options File Macros are supported.
:::

How to Publish Copy Chapter

Excerpt from CLI Usage of electron-builder command:

Publishing:
  --publish, -p  [choices: "onTag", "onTagOrDraft", "always", "never"]

CLI --publish option values:

But please consider using automatic rules instead of explicitly specifying publish:

• If CI server detected, — onTagOrDraft.

• If CI server reports that a tag was pushed, — onTag.

  A release will be drafted (if one doesn't already exist) and artifacts published only if a tag was pushed.

• If npm script named release, — always.

Add to scripts in the development package.json:

"release": "electron-builder"

and if you run yarn release, a release will be drafted (if doesn't already exist) and artifacts published.

Recommended GitHub Releases Workflow Copy Section

1. Draft a new release. Set the "Tag version" to the value of version in your application package.json, and prefix it with v. "Release title" can be anything you want.

   For example, if your application package.json version is 1.0, your draft's "Tag version" would be v1.0.

2. Push some commits. Every CI build will update the artifacts attached to this draft.

3. Once you are done, publish the release. GitHub will tag the latest commit for you.

The benefit of this workflow is that it allows you to always have the latest artifacts, and the release can be published once it is ready.

Continuous Deployment Workflow on Amazon S3 and other non-GitHub Copy Section

This example workflow is modeled on how releases are handled in Maven (it is an example of one of many possible workflows, you are not forced to follow it).

1. Setup your CI to publish on each commit. E.g. "dist": "electron-builder --publish always" in your package.json.
2. Set your version in your application package.json to 1.9.0-snapshot (or 1.9.0-master or whatever you want your development channel to be named). This will publish a file named snapshot.yml and a build named something-snapshot.exe (and corresponding for mac) to S3.
3. When you are ready to deploy, simply change your package version to 1.9.0 and push. This will then produce a latest.yml and something.exe on s3. Usually you'll git-tag this version as well (just to keep track of it).
4. Change the version back to a snapshot version right after, i.e. 1.10.0-snapshot, and commit it.

GitHub Repository {#github-repository-and-bintray-package} Copy Chapter

Detected automatically using:

• repository in the application or development package.json,
• if not set, env
  • TRAVIS_REPO_SLUG
  • or APPVEYOR_REPO_NAME
  • or CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME,
• if no env, from .git/config origin url.

:::warning[The detected repository ships inside your app]
Whatever is detected here becomes the publish/update destination and, for auto-update-capable targets, is written to app-update.yml inside every packaged build - that is where electron-updater looks for updates for the lifetime of that install. A build reports the repository it inferred, including the source it came from - at info level when it comes from the repository field of package.json (deliberate configuration), at warn level when it is picked up from CI environment variables or .git/config:

• update feed inferred from repository info; it will be used as the publish/update destination
  (written to app-update.yml in auto-update-capable targets) - specify it explicitly to be sure
  it stays under your control  reason=owner and repo not specified in the publish configuration
  source=.git/config provider=github owner=my-org repo=my-app

Check that it is the repository you expect, and keep control of it. GitHub releases an owner or repository name for re-registration once it is renamed, transferred or deleted, so anyone who then claims that name can publish releases that already-installed copies of your app will download. Set owner and repo explicitly to avoid depending on detection at all:

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "my-org",
      "repo": "my-app"
    }
  }
}

:::

Publishers

Bitbucket Copy Chapter

:::note[v27: authentication mode]
The Bitbucket publisher selects its auth scheme by whether a username is present:

• With a username (bitbucket.username, or the BITBUCKET_USERNAME env var) → HTTP Basic auth. Use this for a Bitbucket app password or an Atlassian API token (the username is your Bitbucket username or Atlassian account email).
• Without a username → the token is sent as Authorization: Bearer <token> (a repository / project / workspace access token). This is new in v27; previously a token was always sent as Basic auth with the repo owner as the username.

If your CI sets BITBUCKET_TOKEN to an app password / API token without a username, set BITBUCKET_USERNAME too, or the request goes out as Bearer and fails authentication.
:::

{!./builder-util-runtime.Interface.BitbucketOptions.md!}

Github Copy Chapter

:::note[v27: tagNamePrefix replaces vPrefixedTagName]
The GitHub vPrefixedTagName boolean was removed — use tagNamePrefix to control the tag prefix (defaults to "v"; set tagNamePrefix: "" for no prefix). electron-builder migrate-schema rewrites it. Note that v26 ignored an empty tagNamePrefix and still tagged v<version>; v27 honors it, so the migrator rewrites a v26 tagNamePrefix: "" to "v" (with a warning) to keep your existing tag names. (On GitLab, vPrefixedTagName is unchanged and still works.)
:::

{!./builder-util-runtime.Interface.GithubOptions.md!}

GitLab Copy Chapter

{!./builder-util-runtime.Interface.GitlabOptions.md!}

Keygen Copy Chapter

{!./builder-util-runtime.Interface.KeygenOptions.md!}

S3 Copy Chapter

{!./builder-util-runtime.Interface.S3Options.md!}

Snap Store Copy Chapter

{!./builder-util-runtime.Interface.SnapStoreOptions.md!}

Spaces Copy Chapter

{!./builder-util-runtime.Interface.SpacesOptions.md!}

R2 Copy Chapter

To publish to Cloudflare R2:

1. Create an R2 API token with at least Object Read & Write permission on your bucket.
2. Expose its credentials to electron-builder via the CF_R2_ACCESS_KEY_ID and CF_R2_SECRET_ACCESS_KEY environment variables.
3. Enable public access for the bucket via an r2.dev subdomain or a custom domain — R2's S3 API endpoint cannot serve unauthenticated downloads, so electron-updater cannot download updates from it.
4. Set publicUrl to that public base URL.

Auto-updating from R2 requires an electron-updater version that supports the r2 provider: electron-updater >= 7.0.0 (the release line containing this feature).

Note: files are uploaded with a single PUT request, and R2 limits single-PUT uploads to ~5 GiB per object.

{!./builder-util-runtime.Interface.R2Options.md!}

BYO Generic (create-your-own) Copy Chapter

(And maybe submit it upstream in a PR!)
{!./builder-util-runtime.Interface.GenericServerOptions.md!}

Snap (`website/docs/snap.md`) Copy Section

The top-level snapcraft key is the recommended way to configure Snap builds. It requires an explicit base field and separates per-core options cleanly.

The flat snap config key was removed in v27 — use snapcraft instead. electron-builder migrate-schema converts an old snap config to snapcraft automatically. See Migrating from snap to snapcraft if you are upgrading.

Core 24 (Recommended) Copy Chapter

core24 targets Ubuntu 24.04 Noble and requires Electron 25.0.0+ (28.0.0+ recommended). It uses snapcraft v8 (craft-application framework) and brings first-class Wayland, the GNOME extension, and Launchpad remote builds for multi-arch CI.

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "confinement": "strict"
    }
  }
}

Building Snap packages requires a Linux environment (or Docker).

Build Environments Copy Section

Choose one build environment. They are mutually exclusive.

If none is set and you are on Linux, snapcraft's own default (Multipass) is used. On non-Linux platforms you must choose useMultipass or remoteBuild.

LXD

Container-based isolation. Preferred on most Linux CI systems because it does not require nested virtualisation (unlike Multipass).

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "useLXD": true
    }
  }
}

LXD must be installed and the build user must be in the lxd group:

sudo snap install lxd
sudo usermod -aG lxd $USER
lxd init --minimal

Multipass

VM-based isolation. The default choice for local development on macOS and Windows.

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "useMultipass": true
    }
  }
}

Destructive Mode

Builds directly on the host without any VM or container (snapcraft --destructive-mode).

!!! warning
Not recommended for production builds. Destructive mode pollutes the host environment — any library present on the host at build time can end up in the snap, making builds difficult to reproduce. Prefer useLXD or useMultipass for clean builds.

Valid reason(s) to use this mode:

• CI test suites where the environment is already fully controlled.

The gnome extension is incompatible with destructive mode. electron-builder automatically clears extensions when useDestructiveMode is set; explicitly including "gnome" alongside it will throw an error.

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "useDestructiveMode": true,
      "extensions": []
    }
  }
}

Remote Build on Launchpad

Builds on Canonical's Launchpad infrastructure. Works from any platform and supports building for multiple architectures simultaneously (amd64, arm64, armhf).

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "remoteBuild": {
        "enabled": true,
        "buildFor": ["amd64", "arm64"],
        "acceptPublicUpload": true
      }
    }
  }
}

!!! note
Unless privateProject is set, your source code is uploaded to a public Launchpad repository. Set acceptPublicUpload: true to suppress the interactive consent prompt in CI.

Authentication

Remote builds require Snapcraft Store credentials. electron-builder resolves them in this order:

1. remoteBuild.cscLink — base64-encoded credentials or a file path in the build config.
2. SNAP_CSC_LINK — environment variable, same format (CI-recommended).
3. SNAPCRAFT_STORE_CREDENTIALS — plain-text macaroon, read directly by snapcraft.
4. An active interactive snapcraft login session.

Credentials are injected only into the spawned snapcraft subprocess environment and are never exposed through process.env.

This follows the same pattern as WIN_CSC_LINK / CSC_LINK for code signing.

CI Setup

Generate credentials once and store as a CI secret:

# Run locally — output is your CI secret value
snapcraft export-login - | base64 -w0

Then set SNAP_CSC_LINK in your CI environment:

# GitHub Actions
- name: Build and publish snap
  env:
    SNAP_CSC_LINK: ${{ secrets.SNAP_CSC_LINK }}
  run: npx electron-builder --linux snap

:::warning[Classic Confinement]
Snap Store requires manual review and approval for classic confinement. Electron apps typically use strict with appropriate interface plugs.
:::

To reference credentials file directly via the config (useful for monorepos where the credential is managed per-project):

{
  "snapcraft": {
    "base": "core24",
    "core24": {
      "remoteBuild": {
        "enabled": true,
        "cscLink": "file://..."
      }
    }
  }
}

GNOME Extension Copy Section