macOS
Many configuration keys were renamed or restructured in v27 (e.g. mac.sign, win.sign, electronGet, asar, nativeModules, snapcraft, fileOptions). Run electron-builder migrate-schema to rewrite your config automatically, then skim What's New in v27 and the full v27 Breaking Changes.
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
electron-builder supports several macOS distribution formats. Choose based on your distribution channel:
| Target | Best For | Signed? | Notarized? |
|---|---|---|---|
dmg | Standard consumer distribution | Yes | Yes |
zip | Update servers (electron-updater), minimal package | Yes | Yes |
pkg | System-level installs, kernel extensions, launch daemons | Yes | Yes |
mas | Mac App Store distribution | Yes (Mac App Distribution) | No (MAS handles it) |
mas-dev | Local testing of MAS builds | Yes (Apple Development / Mac Developer) | No |
7z, tar.* | Archive formats, custom CDN distribution | Optional | Optional |
dir | Development/debugging — unpacked app | No | No |
The default targets are zip and dmg (both are required for Squirrel.Mac auto-update).
Bundle ID
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
electron-builder supports building for multiple CPU architectures:
| Architecture | CLI Flag | Description |
|---|---|---|
x64 | --x64 | Intel 64-bit (traditional Mac) |
arm64 | --arm64 | Apple Silicon (M1, M2, M3, M4) |
universal | --universal | Fat binary containing both x64 and arm64 |
Universal Binaries
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 (trueby default). Disable only if you have architecture-specific native modules that cannot be fat-binary merged.singleArchFiles— glob pattern for files that may exist in only one of the two per-arch ASAR archives (e.g., pre-built native binaries distributed only for one arch). Matching files inapp.asar.unpackedare copied as-is instead of being merged withlipo.x64ArchFiles— glob pattern for single-arch Mach-O files that are identical in the x64 and arm64 builds (e.g., the same x64 binary shipped in both). These are copied as-is instead of being merged withlipo; any other such file fails the build. Binaries that are already universal in both builds need no pattern.
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
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
macOS apps must be signed to avoid Gatekeeper warnings. See Code Signing for full setup.
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
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).
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
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
You usually do not need to write an entitlements file at all. The defaults are already minimal and correct for a stock Electron app:
| File being signed | Default entitlements |
|---|---|
| The app bundle | com.apple.security.cs.allow-jit |
| Renderer / GPU helpers | com.apple.security.cs.allow-jit |
| Plugin helper | allow-jit, allow-unsigned-executable-memory, disable-library-validation |
| Frameworks, native modules, unpacked binaries | allow-jit plus osx-sign's Chromium-derived device.* / personal-information.* entitlements (default.darwin.plist) |
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.
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
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>
<!-- Required for JIT compilation (e.g., V8 in Electron) -->
<key>com.apple.security.cs.allow-jit</key>
<true/>
<!-- Add only the capabilities your app actually uses, e.g.: -->
<!-- <key>com.apple.security.device.camera</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
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:
| Entitlement | When Needed |
|---|---|
com.apple.security.cs.allow-jit | Always — V8 requires JIT (granted by default) |
com.apple.security.cs.allow-unsigned-executable-memory | Legacy Electron only — not needed by modern V8/Electron and weakens the Hardened Runtime |
com.apple.security.cs.disable-library-validation | Loading frameworks/native modules signed by another team, or unsigned |
com.apple.security.network.client | Outgoing network connections (sandboxed apps) |
com.apple.security.network.server | Listening for connections (sandboxed apps) |
com.apple.security.files.user-selected.read-write | Open/save panels (sandboxed apps) |
com.apple.security.device.camera | Camera access |
com.apple.security.device.microphone | Microphone access |
com.apple.security.app-sandbox | Required for Mac App Store — see MAS |
Notarization requires Hardened Runtime + appropriate entitlements. See Notarization for the complete notarization workflow.
Info.plist Customization
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"
For every target except mas and mas-dev, electron-builder adds App Transport Security entries that electron-updater's local update proxy needs: NSAllowsLocalNetworking and plain-HTTP exceptions for localhost and 127.0.0.1. Electron's default Info.plist already enables NSAllowsArbitraryLoads; electron-builder keeps whatever value you set in extendInfo (and adds it as true if it is missing). To turn it off, set it to false (setting it to null does not remove the key, it is set to true again):
mac:
extendInfo:
NSAppTransportSecurity:
NSAllowsArbitraryLoads: false
Helper Bundle IDs
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:
| Option | Default | Process |
|---|---|---|
helperBundleId | ${appId}.helper | Generic helper |
helperRendererBundleId | ${appId}.helper.Renderer | Renderer process |
helperPluginBundleId | ${appId}.helper.Plugin | Plugin helper |
helperGPUBundleId | ${appId}.helper.GPU | GPU process |
helperEHBundleId | ${appId}.helper.EH | Exception handler |
helperNPBundleId | ${appId}.helper.NP | NP helper |
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
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
Interface: MacConfiguration
Extends
Extended by
Properties
appId?
readonlyoptionalappId?:string|null
The application id. Used as CFBundleIdentifier for MacOS and as Application User Model ID for Windows (NSIS target only, Squirrel.Windows not supported). It is strongly recommended that an explicit ID is set.
Default
com.electron.${name}
Inherited from
PlatformSpecificBuildOptions.appId
artifactName?
readonlyoptionalartifactName?:string|null
The artifact file name template. Defaults to ${productName}-${version}.${ext} (some target can have other defaults, see corresponding options).
Inherited from
PlatformSpecificBuildOptions.artifactName
asar?
readonlyoptionalasar?:boolean|AsarOptions|null
Whether to package the application's source code into an archive, using Electron's archive format.
Node modules that must be unpacked will be detected automatically. Use AsarOptions.unpack to specify additional files to unpack.
Default
true
Inherited from
PlatformSpecificBuildOptions.asar
asarIntegrityDigest?
readonlyoptionalasarIntegrityDigest?:boolean
Whether to embed the ASAR integrity digest into the Electron Framework binary.
The digest covers the ElectronAsarIntegrity entries of Info.plist, so with the enableEmbeddedAsarIntegrityValidation fuse (see electronFuses) the app refuses to launch if those entries are changed, for example to match a modified app.asar. Embedding the digest modifies the Electron Framework, which is then signed again ad hoc; code signing the app replaces that signature.
Applies only when:
- Electron is 41 or later
- the build runs on macOS (
codesignsigns the modified framework again) asaris enabled andasar.disableIntegrityis nottrue
Set to false if you change app.asar or Info.plist after the afterPack hook, sign the app yourself in afterPack, or merge separately built x64 and arm64 apps with @electron/universal yourself (build the universal arch instead).
Default
true
bundleShortVersion?
readonlyoptionalbundleShortVersion?:string|null
The CFBundleShortVersionString. Do not use it unless you need to.
bundleVersion?
readonlyoptionalbundleVersion?:string|null
The CFBundleVersion. Do not use it unless you need to.
category?
readonlyoptionalcategory?:string|null
The application category type, as shown in the Finder via View -> Arrange by Application Category when viewing the Applications directory.
For example, "category": "public.app-category.developer-tools" will set the application category to Developer Tools.
Valid values are listed in Apple's documentation.
compression?
readonlyoptionalcompression?:CompressionLevel|null
The compression level. If you want to rapidly test build, store can reduce build time significantly. maximum doesn't lead to noticeable size difference, but increase build time.
Default
normal
Inherited from
PlatformSpecificBuildOptions.compression
darkModeSupport?
readonlyoptionaldarkModeSupport?:boolean
Whether a dark mode is supported. If your app does have a dark mode, you can make your app follow the system-wide dark mode setting.
Default
false
defaultArch?
readonlyoptionaldefaultArch?:string
The default architecture to build for when no --arch flag is specified.
Defaults to the current machine's architecture.
Inherited from
PlatformSpecificBuildOptions.defaultArch
detectUpdateChannel?
readonlyoptionaldetectUpdateChannel?:boolean
Whether to infer update channel from application version pre-release components. e.g. if version 0.12.1-alpha.1, channel will be set to alpha. Otherwise to latest.
This does not apply to github publishing, which will never auto-detect the update channel.
Default
true
Inherited from
PlatformSpecificBuildOptions.detectUpdateChannel
electronLanguages?
readonlyoptionalelectronLanguages?:string|string[]
The electron locales to keep. By default, all Electron locales used as-is.
Inherited from
PlatformSpecificBuildOptions.electronLanguages
electronUpdaterCompatibility?
readonlyoptionalelectronUpdaterCompatibility?:string|null
The electron-updater compatibility semver range: the
electron-updater versions the installed apps ship, which have to read the update files this build writes. It selects the
.blockmap format (see blockmap), and the build fails when the app's electron-updater does not satisfy it.
Default
>=7
Inherited from
PlatformSpecificBuildOptions.electronUpdaterCompatibility
executableName?
readonlyoptionalexecutableName?:string|null
The executable name. Defaults to productName
Note: Except for Linux, where this would constitute a breaking change in previous behavior and lead to both invalid executable names and Desktop files. Ref comments in: https://github.com/electron-userland/electron-builder/pull/9068
Inherited from
PlatformSpecificBuildOptions.executableName
extendInfo?
readonlyoptionalextendInfo?:any
The extra entries for Info.plist.
extraDistFiles?
readonlyoptionalextraDistFiles?:string|string[] |null
Extra files to put in archive. Not applicable for tar.*.
fileAssociations?
readonlyoptionalfileAssociations?:FileAssociation|FileAssociation[]
The file associations.
Inherited from
PlatformSpecificBuildOptions.fileAssociations
fileOptions?
optionalfileOptions?:FilesBuildOptions|null
Which files to copy into the packaged app (files, the app sources, extraResources and extraFiles), which file extensions to exclude
from it (excludedExts), and whether symlinks among them may lead outside the app and the workspace (allowExternalLinks).
Set at the configuration root, per platform (e.g. mac.fileOptions), or both: a platform's file lists are added to the root ones,
and a platform's excludedExts and allowExternalLinks replace the root ones.
{
"fileOptions": {
"files": ["dist/**/*", "package.json"],
"extraResources": [{ "from": "assets/bin", "to": "bin" }]
}
}
files, extraResources and extraFiles set directly on the configuration or a platform section are moved here
when the configuration is loaded, with a warning. Run electron-builder migrate-schema to update the configuration.
Inherited from
PlatformSpecificBuildOptions.fileOptions
forceCodeSigning?
readonlyoptionalforceCodeSigning?:boolean
Overrides the root forceCodeSigning for this platform: whether to fail the build if the app could not be code-signed,
notarized, or have its auto-update manifests signed, and to verify the signatures it produces. See the root option for
what is enforced. Mac App Store builds cascade mac → mas (→ masDev for mas-dev), like every other option, so mas.forceCodeSigning / masDev.forceCodeSigning apply to their targets only.
Default
false
Inherited from
PlatformSpecificBuildOptions.forceCodeSigning
generateUpdatesFilesForAllChannels?
readonlyoptionalgenerateUpdatesFilesForAllChannels?:boolean
Please see Building and Releasing using Channels.
Default
false
Inherited from
PlatformSpecificBuildOptions.generateUpdatesFilesForAllChannels
helperBundleId?
readonlyoptionalhelperBundleId?:string|null
The bundle identifier to use in the application helper's plist.
Default
${appBundleIdentifier}.helper
helperEHBundleId?
readonlyoptionalhelperEHBundleId?:string|null
The bundle identifier to use in the EH helper's plist.
Default
${appBundleIdentifier}.helper.EH
helperGPUBundleId?
readonlyoptionalhelperGPUBundleId?:string|null
The bundle identifier to use in the GPU helper's plist.
Default
${appBundleIdentifier}.helper.GPU
helperNPBundleId?
readonlyoptionalhelperNPBundleId?:string|null
The bundle identifier to use in the NP helper's plist.
Default
${appBundleIdentifier}.helper.NP
helperPluginBundleId?
readonlyoptionalhelperPluginBundleId?:string|null
The bundle identifier to use in the Plugin helper's plist.
Default
${appBundleIdentifier}.helper.Plugin
helperRendererBundleId?
readonlyoptionalhelperRendererBundleId?:string|null
The bundle identifier to use in the Renderer helper's plist.
Default
${appBundleIdentifier}.helper.Renderer
icon?
readonlyoptionalicon?:string|null
The path to application icon.
Accepts .icns (legacy) or .icon (Icon Composer asset).
If a .icon asset is provided, it will be preferred and compiled to an asset catalog.
Default
build/icon.icns
Overrides
PlatformSpecificBuildOptions.icon
minimumSystemVersion?
readonlyoptionalminimumSystemVersion?:string|null
The minimum version of macOS required for the app to run. Corresponds to LSMinimumSystemVersion.
notarize?
readonlyoptionalnotarize?:boolean
Whether to notarize the app with @electron/notarize.
- unset (the default): notarize when notarization credentials are set, otherwise skip it with a warning.
true: notarization is required: the build fails when no credentials are set, wherever notarization would run (a macOS host, outside a pull-request build, with signing not turned off), at build start and when notarizing.false: never notarize (for an ad-hoc or development-signed app, or one notarized in anafterSignhook).
The credentials are one of the following sets of environment variables:
APPLE_API_KEY(path to the.p8file, or its contents base64-encoded),APPLE_API_KEY_IDandAPPLE_API_ISSUER.APPLE_ID,APPLE_APP_SPECIFIC_PASSWORD, andAPPLE_TEAM_IDAPPLE_KEYCHAINandAPPLE_KEYCHAIN_PROFILE
For security reasons it is recommended to use the first option (see https://github.com/electron-userland/electron-builder/issues/7859)
protocols?
The URL protocol schemes.
Inherited from
PlatformSpecificBuildOptions.protocols
publish?
optionalpublish?:Publish
Publisher configuration. See Auto Update for more information.
Inherited from
PlatformSpecificBuildOptions.publish
releaseInfo?
readonlyoptionalreleaseInfo?:ReleaseInfo
The release info. Intended for command line usage:
-c.releaseInfo.releaseNotes="new features"
Inherited from
PlatformSpecificBuildOptions.releaseInfo
sign?
readonlyoptionalsign?:string|ElectronSignOptions|CustomMacSign|null
Codesigning configuration. The signing certificate is selected via sign.identity (or the
CSC_LINK / CSC_NAME environment variables).
- Not set (default): electron-builder auto-discovers a valid certificate in the keychain. If none is found, signing is skipped.
null: skip signing entirely.string: path or module ID of a file that exports a CustomMacSign function.- CustomMacSign: inline custom signing function (JS/TS config only).
- ElectronSignOptions: options forwarded directly to
@electron/osx-sign.
See
- ElectronSignOptions
- https://www.electron.build/docs/features/code-signing
target?
readonlyoptionaltarget?:TargetConfiguration|MacOsTargetName| TargetConfiguration | MacOsTargetName[] |null
The target package type: list of default, dmg, mas, mas-dev, pkg, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2, dir.
Note: Squirrel.Mac auto update mechanism requires both dmg and zip to be enabled, even when only dmg is used. Disabling zip will break auto update in dmg packages.
Default
default (dmg and zip for Squirrel.Mac)
Overrides
PlatformSpecificBuildOptions.target
universal?
readonlyoptionaluniversal?:ElectronUniversalOptions|null
Options forwarded to @electron/universal when building a universal (multi-arch) app.
Has no effect unless the target arch is universal.
See
- ElectronUniversalOptions
- https://github.com/electron/universal
updateManifest?
readonlyoptionalupdateManifest?:false|UpdateManifestSigningOptions|null
Ed25519 signing of the auto-update manifest (latest*.yml). Each manifest is signed and its public key is
embedded into app-update.yml, so electron-updater verifies the signature before downloading an update.
Signing is required. Publishing a build that emits auto-update metadata fails unless a signing key
resolves. Generate one once with electron-builder create-update-key, then supply it via
ELECTRON_BUILDER_UPDATE_SIGN_KEY (the PEM file, base64-encoded) / ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE (its path),
preferred in CI, or via signingKey / signingKeyFile below. Leaving this option unset — or null — keeps signing required and
resolves the key from the environment; null is not an opt-out.
Set to false, the only opt-out, to ship unsigned manifests. Every build that produces a manifest then
logs a warning. false also short-circuits the environment variables, so a leftover
ELECTRON_BUILDER_UPDATE_SIGN_KEY in CI cannot re-enable signing by accident.
The requirement is enforced when a publish policy is in effect (--publish) or forceCodeSigning is set; any other
build warns instead, so local builds and pipelines that sign the manifest in a later step of their own are
unaffected. It is also waived when every publish provider has publishAutoUpdate: false, since no manifest is
emitted then, and for a build whose targets write no update info (e.g. only snap, flatpak, MSI/MSIX, portable,
mas/pkg or plain archives). A publishing (or forceCodeSigning) build checks for the key at build start, before
anything is packed or uploaded. Every signed manifest is read back and verified before it is written.