DMG

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

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

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

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 background@2x.png. 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

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

Field	Description
`x`, `y`	Position in the DMG window (pixels from top-left)
`type`	`file` — the app itself; `link` — a symlink (e.g., to `/Applications`)
`path`	Only for `link` type — the symlink destination
`name`	Optional display name override

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

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

The format option controls the compression algorithm:

Format	Description	Use Case
`UDZO`	zlib-compressed (default)	Good balance of size and compatibility
`ULFO`	LZFSE-compressed	Faster decompression, macOS 10.11+ only
`UDBZ`	bzip2-compressed	Better compression than UDZO, slower
`UDRO`	Read-only, uncompressed	Largest size, fastest to open
`UDRW`	Read-write	Only for development/testing

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.

DMG Size

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

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

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

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)

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.

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)

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

Filename	Language
`license_en.txt` or `eula_en.txt`	English
`license_de.rtf`	German
`license_fr.html`	French
`license_ja.txt`	Japanese
`license_zh_CN.txt`	Simplified Chinese

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.

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

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

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

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

Interface: DmgOptions

Extends

TargetSpecificOptions

Properties

artifactName?

readonly optional artifactName?: string | null

The artifact file name template.

Inherited from

TargetSpecificOptions.artifactName

background?

optional background?: string | null

The path to background image (default: build/background.tiff or build/background.png if exists). The resolution of this file determines the resolution of the installer window. If background is not specified, use window.size. Default locations expected background size to be 540x380.

See

DMG with Retina background support.

backgroundColor?

optional backgroundColor?: string | null

The background color (accepts css colors). Used when no background image is set.

Default

#ffffff

badgeIcon?

optional badgeIcon?: string | null

The path to DMG icon (badge icon), which will be shown when mounted, relative to the build resources or to the project directory.

contents?

optional contents?: DmgContent[]

The content — to customize icon locations. The x and y coordinates refer to the position of the center of the icon (at 1x scale), and do not take the label into account.

filesystem?

readonly optional filesystem?: "HFS+" | "APFS" | null

The filesystem for the DMG volume (e.g. "APFS" or "HFS+") This will be changed to APFS in the next major release, so it is recommended to set it explicitly to HFS+ if you want to keep using HFS+ (e.g. for better compatibility with older macOS versions).

Default

HFS+

format?

optional format?: "UDRW" | "UDRO" | "UDCO" | "UDZO" | "UDBZ" | "ULFO"

The disk image format. ULFO (lzfse-compressed image (OS X 10.11+ only)).

Default

UDZO

icon?

optional icon?: string | null

The path to DMG icon (volume icon), which will be shown when mounted, relative to the build resources or to the project directory. Defaults to the application icon (build/icon.icns).

iconSize?

readonly optional iconSize?: number | null

The size of all the icons inside the DMG.

Default

iconTextSize?

readonly optional iconTextSize?: number | null

The size of all the icon texts inside the DMG.

Default

internetEnabled?

readonly optional internetEnabled?: boolean

Whether to create internet-enabled disk image (when it is downloaded using a browser it will automatically decompress the image, put the application on the desktop, unmount and remove the disk image file).

Default

false

license?

optional license?: string | Record<string, string> | null

License agreement to display when the DMG is mounted.

Accepts a single file path (.rtf, .txt, or .html) used as the English/default license, or a language-code → file-path map for multi-language builds.

When set, this takes precedence over the file-naming convention (license_en.txt, etc. in the build resources directory). Paths are resolved relative to the build resources directory or project root.

Examples

dmg:
  license: "build/license.rtf"

dmg:
  license:
    en_US: "build/license.rtf"
    de_DE: "build/license_de.txt"
    ja_JP: "build/license_ja.txt"

If not set, electron-builder scans the build resources directory for license_LANG.{rtf,txt,html} files automatically.

publish?

optional publish?: Publish

Inherited from

TargetSpecificOptions.publish

shrink?

readonly optional shrink?: boolean

Whether to shrink the DMG filesystem to the minimum size after copying files. Set to false to preserve the explicit size you specified.

Default

true

sign?

readonly optional sign?: boolean

Whether to sign the DMG or not. Signing is not required and will lead to unwanted errors in combination with notarization requirements.

Default

false

size?

readonly optional size?: string | null

The initial size of the DMG filesystem. Accepts the same syntax as the -size argument to hdiutil, e.g. "150m", "4g". If not specified, the size is calculated automatically. Set this explicitly for large apps or apps with sparse files to avoid "No space left on device" errors.

title?

readonly optional title?: string | null

The title of the produced DMG, which will be shown when mounted (volume name).

Macro ${productName}, ${version} and ${name} are supported.

Default

${productName} ${version}

window?

optional window?: DmgWindow

The DMG window position and size. With y co-ordinates running from bottom to top.

The Finder makes sure that the window will be on the user’s display, so if you want your window at the top left of the display you could use "x": 0, "y": 100000 as the x, y co-ordinates. It is not to be possible to position the window relative to the top left or relative to the center of the user’s screen.

When to Use DMG​

Window Customization​

Background Image​

Icon Layout​

Volume Icon and Title​

Disk Image Format​

DMG Size​

Signing the DMG​

Internet-Enabled DMGs​

DMG License​

Configuration-based (recommended)​

File-naming convention (automatic discovery)​

Customizing License Button Labels​

Complete Example​

Troubleshooting​

Configuration​

Interface: DmgOptions

Extends​

Properties​

artifactName?​

Inherited from​

background?​

See​

backgroundColor?​

Default​

badgeIcon?​

contents?​

filesystem?​

Default​

format?​

Default​

icon?​

iconSize?​

Default​

iconTextSize?​

Default​

internetEnabled?​

Default​

license?​

Examples​

publish?​

Inherited from​

shrink?​

Default​

sign?​

Default​

size?​

title?​

Default​

window?​

When to Use DMG

Window Customization

Background Image

Icon Layout

Volume Icon and Title

Disk Image Format

DMG Size

Signing the DMG

Internet-Enabled DMGs

DMG License

Configuration-based (recommended)

File-naming convention (automatic discovery)

Customizing License Button Labels

Complete Example

Troubleshooting

Configuration

Extends

Properties

artifactName?

Inherited from

background?

See

backgroundColor?

Default

badgeIcon?

contents?

filesystem?

Default

format?

Default

icon?

iconSize?

Default

iconTextSize?

Default

internetEnabled?

Default

license?

Examples

publish?

Inherited from

shrink?

Default

sign?

Default

size?

title?

Default

window?