Skip to main content

CLI

electron-builder

Build

Commands:
  electron-builder build                    Build                                [default]
  electron-builder install-app-deps         Install app deps
  electron-builder node-gyp-rebuild         Rebuild own native code
  electron-builder publish                  Publish a list of artifacts
  electron-builder create-self-signed-cert  Create self-signed code signing cert for Windo
                                  ws apps
  electron-builder start                    Run application in a development mode using el
                                  ectron-webpack
  electron-builder clear-cache              Clear the electron-builder default cache direc
                                  tory
  electron-builder create-update-key        Generate an Ed25519 keypair for signing auto-u
                                  pdate manifests
  electron-builder migrate-schema           Migrate build config from v26 to v27 format
  electron-builder verify [dir]             Verify code signatures, notarization and updat
                                  e-manifest signatures of built artifacts

Building:
  -m, -o, --mac, --macos       Build for macOS, accepts target list (see https:/
                               /www.electron.build/mac).                 [array]
  -l, --linux                  Build for Linux, accepts target list (see https:/
                               /www.electron.build/linux)                [array]
  -w, --win, --windows         Build for Windows, accepts target list (see https
                               ://www.electron.build/win)                [array]
      --x64                    Build for x64                           [boolean]
      --ia32                   Build for ia32                          [boolean]
      --armv7l                 Build for armv7l                        [boolean]
      --arm64                  Build for arm64                         [boolean]
      --universal              Build for universal                     [boolean]
      --dir                    Build unpacked dir. Useful to test.     [boolean]
      --prepackaged, --pd      The path to prepackaged app (to pack in a distrib
                               utable format)
      --projectDir, --project  The path to project directory. Defaults to curren
                               t working directory.
  -c, --config                 The path to an electron-builder config. Defaults
                               to `electron-builder.yml` (or `json`, or `json5`,
                                or `js`, or `ts`), see https://www.electron.buil
                               d/configuration

Publishing:
  -p, --publish  Publish artifacts, see https://www.electron.build/publish
                [choices: "onTag", "onTagOrDraft", "always", "never", undefined]

Other:
      --help     Show help                                             [boolean]
      --version  Show version number                                   [boolean]

Examples:
  electron-builder -mwl                     build for macOS, Windows and Linux
  electron-builder --linux deb tar.xz       build deb and tar.xz for Linux
  electron-builder --win --arm64            build for Windows arm64
  electron-builder -c.extraMetadata.foo=ba  set package.json property `foo` to `
  r                                         bar`
  electron-builder --config.nsis.unicode=f  configure unicode options for NSIS
  alse

See https://electron.build for more documentation.

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.

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​

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 <path> 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, forceCodeSigning). Advisories never change the file. See what it does and does not do.
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.

verify​

New in v27. Checks the signatures of a build's output and exits with code 1 when a check fails — a post-build gate for CI, the checks forceCodeSigning makes during a build plus what can only be seen afterwards.

electron-builder verify                    # the output directory (directories.output) of the project configuration
electron-builder verify path/to/dist       # another directory, e.g. downloaded build artifacts
electron-builder verify --allow-unverified # only warn about checks that cannot run on this host

What it checks:

  • Update manifests — every latest*.yml (found by its content, also a further provider's in a subdirectory, such as nsis-web/<provider>/latest.yml; symlinks in the output are not followed) must be signed by a key in the trust list (updateManifestPublicKey) that each packaged app of its platform embeds in app-update.yml, the check electron-updater makes. Without a packaged app in the directory, it uses updateManifest.publicKey instead, and without that the manifest cannot be verified. verify uses public keys only: it never loads a signing key, from the configuration or ELECTRON_BUILDER_UPDATE_SIGN_KEY / ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE, so a cutover release signed outside its embedded trust list (allowSigningKeyOutsideTrustList) is reported as skipped. Every file a manifest lists must match an artifact by sha512 and size, which catches an artifact changed after the manifest was written.
  • macOS — every .app must have a valid code signature (codesign --verify --deep --strict) and, outside the Mac App Store, a stapled notarization ticket (stapler validate). A .pkg must be signed (pkgutil --check-signature) and notarized, and a DMG with dmg.sign: true must be signed. Any valid signature counts.
  • Windows — installers, .msi / AppX / MSIX packages and the app executable must carry a valid Authenticode signature, and the update installers must match the publisherName electron-updater verifies them against.

The options of the project configuration are honored: updateManifest: false, mac.notarize: false, mac.sign: null (mas.sign / masDev.sign for Mac App Store apps), win.sign: false and win.signExts exclusions turn the checks they affect into warnings. Pass the configuration of the build with -c / --config and --projectDir as for a build.

codesign, stapler, pkgutil and Windows PowerShell are started by absolute path, from toolsets.executables of the configuration or their default locations, never from PATH.

A check that cannot run on this host fails, unless --allow-unverified is passed: macOS checks need macOS, the signature hash of a Windows file can only be validated on Windows (elsewhere only its signer is read), and an update manifest needs a trust list to be verified against. Store-only AppX/MSIX packages are unsigned by design: exclude them with win.signExts: ["!.appx"].

In CI, verify before you publish, for example on macOS:

electron-builder --mac --publish never
electron-builder verify
electron-builder publish -f dist/*.dmg dist/*.zip dist/*.blockmap dist/latest-mac.yml

electron-builder publish -f checks an update manifest before it uploads anything: it must be signed, and, when updateManifest.publicKey is set, signed by one of those keys. See Signed update manifests are required.

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

build for macOS, Windows and Linux

electron-builder -mwl

build deb and tar.xz for Linux

electron-builder --linux deb tar.xz

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

set package.json property foo to bar

electron-builder -c.extraMetadata.foo=bar

configure unicode options for NSIS

electron-builder -c.nsis.unicode=false

Target​

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

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​

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