Skip to main content
The top-level dmg key contains options for building DMG installers for macOS.

​
Basic Example

{
  "dmg": {
    "title": "${productName} ${version}",
    "icon": "build/icon.icns",
    "background": "build/background.png",
    "contents": [
      {
        "x": 130,
        "y": 220
      },
      {
        "x": 410,
        "y": 220,
        "type": "link",
        "path": "/Applications"
      }
    ]
  }
}

​
DMG License

To add a license to DMG, create file license_LANG_CODE.txt in the build resources. Multiple license files in different languages are supported — use lang postfix (e.g. _de, _ru). For example, create files license_de.txt and license_en.txt in the build resources. If OS language is german, license_de.txt will be displayed. See map of language code to name.

​
Custom License Buttons

You can also change the default button labels of the DMG by passing a json file named licenseButtons_LANG_CODE.json. The german file would be named: licenseButtons_de.json. The file should have the following format: 
{
  "lang": "English",
  "agree": "Agree",
  "disagree": "Disagree",
  "print": "Print",
  "save": "Save",
  "description": "Here is my own description"
}

​
Configuration Options

​
Appearance

​
background
string
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
string
The background color (accepts css colors).Default: #ffffff (white) if no background image
​
icon
string
The path to DMG icon (volume icon), which will be shown when mounted, relative to the build resources or to the project directory.Default: Application icon (build/icon.icns)
​
badgeIcon
string
The path to DMG icon (badge icon), which will be shown when mounted, relative to the build resources or to the project directory.
​
iconSize
number
default:"80"
The size of all the icons inside the DMG.
​
iconTextSize
number
default:"12"
The size of all the icon texts inside the DMG.
​
title
string
default:"${productName} ${version}"
The title of the produced DMG, which will be shown when mounted (volume name).Macro ${productName}, ${version} and ${name} are supported.

​
Window Configuration

​
window
object
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 possible to position the window relative to the top left or relative to the center of the user’s screen.
Properties:
​
window.x
number
default:"400"
The X position relative to left of the screen.
​
window.y
number
default:"100"
The Y position relative to bottom of the screen.
​
window.width
number
The width. Defaults to background image width or 540.
​
window.height
number
The height. Defaults to background image height or 380.

​
Content Layout

​
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.Example:
{
  "contents": [
    {
      "x": 130,
      "y": 220
    },
    {
      "x": 410,
      "y": 220,
      "type": "link",
      "path": "/Applications"
    }
  ]
}
Content Properties:
​
contents[].x
number
required
The device-independent pixel offset from the left of the window to the center of the icon.
​
contents[].y
number
required
The device-independent pixel offset from the top of the window to the center of the icon.
​
contents[].type
'link' | 'file' | 'dir'
The type of content.
​
contents[].name
string
The name of the file within the DMG. Defaults to basename of path.
​
contents[].path
string
The path of the file within the DMG.

​
Format and Size

​
format
'UDRW' | 'UDRO' | 'UDCO' | 'UDZO' | 'UDBZ' | 'ULFO'
default:"UDZO"
The disk image format.
  • ULFO: lzfse-compressed image (OS X 10.11+ only)
  • UDZO: zlib-compressed image (default)
  • UDBZ: bzip2-compressed image
  • UDCO: ADC-compressed image
  • UDRW: read/write image
  • UDRO: read-only image
​
size
string
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.
​
shrink
boolean
default:"true"
Whether to shrink the DMG filesystem to the minimum size after copying files.Set to false to preserve the explicit size you specified.

​
Advanced Options

​
internetEnabled
boolean
default:"false"
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.
​
sign
boolean
default:"false"
Whether to sign the DMG or not.
Signing is not required and will lead to unwanted errors in combination with notarization requirements.

Build docs developers (and LLMs) love

Get started for freeTalk to us