macOS Packaging

Application Bundle

Package your app as a standard macOS .app bundle:

bash
wails3 package GOOS=darwin

This creates bin/<AppName>.app containing:

  • The compiled binary in Contents/MacOS/
  • App icon in Contents/Resources/ (from icons.icns or, when present, from an asset catalog Assets.car)
  • Info.plist with app metadata

Universal Binary

Build for both Apple Silicon and Intel Macs:

bash
wails3 task darwin:package:universal

This creates a single .app that runs natively on both architectures. Universal binaries can be built on any platform — on Linux and Windows, wails3 tool lipo is used automatically.

Customizing the Bundle

Edit build/darwin/Info.plist to customize:

  • Bundle identifier (CFBundleIdentifier)
  • App name and version
  • Minimum macOS version
  • File associations
  • URL schemes

The app icon is generated from assets in the build/ directory. Use the generate:icons task:

bash
wails3 task common:generate:icons

This uses build/appicon.png to produce darwin/icons.icns and windows/icon.ico. On macOS you can also provide build/appicon.icon (Icon Composer format): the task passes -iconcomposerinput appicon.icon -macassetdir darwin, which produces Assets.car and darwin/icons.icns from the .icon file (skipped on non-macOS platforms). When Assets.car is present, run the update:build-assets task so that Info.plist and CFBundleIconName are updated accordingly:

bash
wails3 task common:update:build-assets

To run the icon command manually from the build/ directory:

bash
cd build
wails3 generate icons -input appicon.png -macfilename darwin/icons.icns -windowsfilename windows/icon.ico -iconcomposerinput appicon.icon -macassetdir darwin

Code Signing

Sign your app for distribution:

bash
# Using the wrapper (auto-detects platform)
wails3 sign GOOS=darwin

# Or using the task directly
wails3 task darwin:sign

Configure signing in build/darwin/Taskfile.yml:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  ENTITLEMENTS: "build/darwin/entitlements.plist"

Notarization

For apps distributed outside the Mac App Store, Apple requires notarization:

bash
wails3 task darwin:sign:notarize

First, store your credentials. Either run the interactive wizard (wails3 setup signing) or call notarytool directly:

bash
xcrun notarytool store-credentials "my-notarize-profile" \
  --apple-id "you@email.com" \
  --team-id "TEAMID" \
  --password "app-specific-password"

Configure in build/darwin/Taskfile.yml:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"

See Signing Applications for details.

DMG Installer

The shipped Wails 3 template provides wails3 task darwin:package:dmg. It creates the .app first and then builds a styled DMG with the DMG library. By default, the DMG uses a Wails-branded gradient backdrop with the red dragon mark and WAILS wordmark.

bash
wails3 task darwin:package:dmg

The lower-level darwin:create:dmg task creates a DMG from an existing .app bundle and can be configured directly from the Taskfile:

vars:
  # These are the template defaults; override them when needed.
  DMG_BACKGROUND: build/darwin/dmg-background.png
  DMG_VOLUME_ICON: build/darwin/icons.icns
  DMG_FILE_ICON: build/darwin/dmg-file-icon.icns
  DMG_WINDOW_WIDTH: 540
  DMG_WINDOW_HEIGHT: 380
  DMG_FILES: "Install.command=build/darwin/Install.command,README.txt=README.md"

Default Layout

The generated DMG contains:

  • The application bundle on the left
  • An Applications link on the right
  • A Finder window sized to 540×380 pixels
  • A 96-point icon size with labels beneath each icon
  • The Wails-branded background from build/darwin/dmg-background.png

The application and Applications icons are positioned relative to the configured window dimensions, so changing DMG_WINDOW_WIDTH or DMG_WINDOW_HEIGHT keeps the default two-icon layout proportionally spaced. For the best result, use a background image with the same pixel dimensions as the Finder window.

Replacing the DMG Assets

The generated files under build/darwin/ are normal project assets and may be replaced:

  • DMG_BACKGROUND controls the image displayed behind the Finder window contents.
  • DMG_VOLUME_ICON controls the icon shown for the mounted volume.
  • DMG_FILE_ICON controls the icon shown for the resulting .dmg file in Finder.

The volume icon and DMG file icon are separate resources. Replacing the application icon does not automatically replace either of them.

Adding Extra Files

Use DMG_FILES to include installer scripts, release notes, licences, or other resources alongside the application. The value is a comma-separated list of name=path pairs:

vars:
  DMG_FILES: "Install.command=build/darwin/Install.command,README.txt=README.md"

The name before = is the filename shown inside the DMG. The path after = is the source file in the project. Leading and trailing whitespace is ignored.

Each displayed name must be unique. Extra files cannot replace entries already created by the packager, including the application bundle or the Applications entry. A conflicting name causes packaging to fail with an error rather than producing a broken DMG.

Troubleshooting

“App is damaged and can’t be opened”

The app isn’t signed. Either sign it with a Developer ID certificate, or users can bypass Gatekeeper:

bash
xattr -cr /path/to/YourApp.app

Notarization fails

Common issues:

  • Invalid credentials: Re-run xcrun notarytool store-credentials (or wails3 setup signing)
  • Hardened runtime required: Ensure entitlements include com.apple.security.cs.allow-unsigned-executable-memory if needed
  • Missing timestamp: The signing process should include a timestamp automatically

Cross-compiled app won’t run

Cross-compiled macOS binaries aren’t signed. Transfer to a Mac and sign before testing:

bash
codesign --force --deep --sign - YourApp.app
Edit page

Last updated: