macOS Packaging

Application Bundle

Package your app as a standard macOS .app bundle:

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:

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:

wails3 task 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:

wails3 task update:build-assets

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

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:

# 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:

wails3 task darwin:sign:notarize

First, store your credentials:

wails3 signing credentials \
  --apple-id "you@email.com" \
  --team-id "TEAMID" \
  --password "app-specific-password" \
  --profile "my-notarize-profile"

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

Create a DMG disk image for distribution:

wails3 task darwin:create:dmg

Tip

Customize the DMG background and layout by editing build/darwin/dmg/ assets.

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:

xattr -cr /path/to/YourApp.app

Notarization fails

Common issues:

• Invalid credentials: Re-run wails3 signing credentials
• 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:

codesign --force --deep --sign - YourApp.app