Linux Packaging

Package Formats

Package your app for Linux distribution:

wails3 package GOOS=linux

This creates multiple formats in the bin/ directory:

• AppImage: Portable, runs on any Linux distribution
• DEB: For Debian, Ubuntu, and derivatives
• RPM: For Fedora, RHEL, and derivatives
• Arch: For Arch Linux and derivatives

Individual Formats

Build specific formats:

wails3 task linux:create:appimage
wails3 task linux:create:deb
wails3 task linux:create:rpm
wails3 task linux:create:aur

Customizing Packages

Desktop Entry

The .desktop file controls how your app appears in application menus. It’s generated from values in build/linux/Taskfile.yml:

vars:
  APP_NAME: 'MyApp'
  EXEC: 'MyApp'
  ICON: 'MyApp'
  CATEGORIES: 'Development;'

Package Metadata

Edit build/linux/nfpm/nfpm.yaml to customize DEB and RPM packages:

name: myapp
version: 1.0.0
maintainer: Your Name <you@example.com>
description: My awesome Wails application
homepage: https://example.com
license: MIT

AppImage

AppImage configuration is in build/linux/appimage/. The app icon comes from build/appicon.png.

Signing Packages

Sign DEB and RPM packages with a PGP key:

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

# Or using tasks directly
wails3 task linux:sign:deb
wails3 task linux:sign:rpm
wails3 task linux:sign:packages  # Both

Configure signing in build/linux/Taskfile.yml:

vars:
  PGP_KEY: "path/to/signing-key.asc"
  SIGN_ROLE: "builder"  # origin, maint, archive, or builder

Store your key password:

wails3 setup signing

See Signing Applications for details.

Building for ARM

wails3 build GOOS=linux GOARCH=arm64
wails3 package GOOS=linux GOARCH=arm64

Note

ARM64 builds from x86_64 hosts use Docker for CGO cross-compilation.

GTK4 Support (Experimental)

Wails v3 includes experimental support for GTK4 with WebKitGTK 6.0. By default, Wails uses GTK3 with WebKit2GTK 4.1. GTK4 support is opt-in via a build tag.

Experimental

GTK4 support is experimental and may have issues. Please report problems to GitHub issue #4957.

Dependencies

Install GTK4 and WebKitGTK 6.0 development libraries:

# Ubuntu/Debian
sudo apt install libgtk-4-dev libwebkitgtk-6.0-dev

# Fedora
sudo dnf install gtk4-devel webkitgtk6.0-devel

# Arch
sudo pacman -S gtk4 webkitgtk-6.0

The required pkg-config packages are gtk4 and webkitgtk-6.0.

Building with GTK4

Use the -tags gtk4 flag:

wails3 build -tags gtk4

Or directly with Go:

go build -tags gtk4 -o myapp .

Known Differences from GTK3

• File dialogs: GTK4 uses xdg-desktop-portal for file dialogs, which means some dialog options (like default directory, custom filters display) behave differently. See Dialogs Reference - Linux GTK4 Limitations for details.
• Menu style: GTK4 supports a LinuxMenuStylePrimaryMenu option that displays a hamburger button (☰) in the header bar, following GNOME HIG. See Window API - Linux MenuStyle.
• DPI scaling: GTK4 uses gdk_monitor_get_scale (GTK 4.14+) for fractional scaling support.

Checking Your Build

Run wails3 doctor to verify your setup. GTK4 dependencies will be shown as optional/experimental.

Troubleshooting

AppImage won’t run

Make it executable:

chmod +x MyApp-x86_64.AppImage

Missing dependencies

If the app fails to start, check for missing WebKit dependencies:

# Debian/Ubuntu
sudo apt install libwebkit2gtk-4.1-0

# Fedora
sudo dnf install webkit2gtk4.1

# Arch
sudo pacman -S webkit2gtk-4.1

No C compiler found

The build system needs GCC or Clang for CGO:

# Debian/Ubuntu
sudo apt install build-essential

# Fedora
sudo dnf install gcc

# Arch
sudo pacman -S base-devel

Alternatively, run wails3 task setup:docker and the build system will use Docker automatically.

AppImage strip compatibility

On modern Linux distributions (Arch Linux, Fedora 39+, Ubuntu 24.04+), system libraries are compiled with .relr.dyn ELF sections for more efficient relocations. The linuxdeploy tool used to create AppImages bundles an older strip binary that cannot process these modern sections.

Wails automatically detects this situation by checking system GTK libraries before building the AppImage. When detected, stripping is disabled (NO_STRIP=1) to ensure compatibility.

What this means:

• AppImages will be slightly larger (~20-40%) on affected systems
• The application functionality is not affected
• This is handled automatically—no action required

If you need smaller AppImages on modern systems, you can install a newer strip binary and configure linuxdeploy to use it instead of its bundled version.