macOS Packaging

Package your Wails application for macOS distribution

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

Bundle Resources

Contents/Resources/ is the standard place for read-only files that ship with a macOS app. Use it for larger templates, seed data, media, language packs, or other payloads that should be opened on demand rather than compiled into the Go executable with embed.

Wails already places the application icon in this directory. To add your own files, place them in a source directory such as build/resources/, then add a copy step to the create:app:bundle task in build/darwin/Taskfile.yml:

yaml

tasks:
  create:app:bundle:
    cmds:
      # Existing bundle creation commands...
      - |
          if [ -d build/resources ]; then
            cp -R build/resources/. "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/Resources/"
          fi

If you use the Taskfile’s darwin:run task, add the equivalent command to its run task, targeting {{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Resources/.

Reading Resources from Go

Import the macOS platform package:

import (
	"io/fs"

	"github.com/wailsapp/wails/v3/pkg/mac"
)

For small files, use LoadResource:

func loadSplash() ([]byte, error) {
	return mac.LoadResource("images/splash.png")
}

For larger files, use ResourceFS. It returns an io/fs.FS rooted at Contents/Resources, so callers can open and stream a resource without first loading it all into a Go byte slice:

func openCatalogue() (fs.File, error) {
	resources, err := mac.ResourceFS()
	if err != nil {
		return nil, err
	}

	return resources.Open("catalogue/defaults.json")
}

Resource names are slash-separated paths relative to Contents/Resources. ResourceFS and LoadResource return mac.ErrNotInAppBundle unless the executable runs from .app/Contents/MacOS.

Treat bundle resources as immutable. Changing files inside a signed application invalidates its code signature; store downloaded, generated, or user-editable data in the user’s Application Support directory instead.

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:

yaml

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:

yaml

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:

yaml

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:

yaml

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