DMG

The top-level dmg key contains 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, create license files in your build resources directory.

Single Language

Create license.txt, license.rtf, or license.html in your build resources directory (default: build/).

Multiple Languages

Create files with a language code suffix. For example:

• license_en.txt — English
• license_de.txt — German
• license_fr.txt — French
• license_ja.txt — Japanese
• license_zh_CN.txt — Simplified Chinese

The displayed license is selected based on the user's macOS language preference. See the language code reference for supported codes.

Customizing License Button Labels

Override the default button text (Agree/Disagree/Print/Save) for each language by creating licenseButtons_LANG_CODE.json files:

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

Name the file licenseButtons_en.json for English, licenseButtons_de.json for German, etc.

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

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: Confirm the license file is in the correct build resources directory and has the correct filename format (license.txt, license_en.txt, etc.).

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.

---

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

80

---

iconTextSize?

readonly optional iconTextSize?: number | null

The size of all the icon texts inside the DMG.

Default

12

---

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

---

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.