wails/website/docs/guides/linux-distro-support.mdx

# Linux Distro Support

## Overview

Wails offers Linux support but providing installation instructions for all available distributions is an impossible task.
Instead, Wails tries to determine if the packages you need to develop applications are available via your system's package
manager. Currently, we support the following package managers:

- apt
- dnf
- emerge
- eopkg
- nixpkgs
- pacman
- zypper

## Adding package names

There may be circumstances where your distro uses one of the supported package managers but the package name
is different. For example, you may use an Ubuntu derivative, but the package name for gtk may be different. Wails
attempts to find the correct package by iterating through a list of package names.
The list of packages are stored in the packagemanager specific file in the `v2/internal/system/packagemanager`
directory. In our example, this would be `v2/internal/system/packagemanager/apt.go`.

In this file, the list of packages are defined by the `Packages()` method:

```go
func (a *Apt) Packages() packagemap {
	return packagemap{
		"libgtk-3": []*Package{
			{Name: "libgtk-3-dev", SystemPackage: true, Library: true},
		},
		"libwebkit": []*Package{
			{Name: "libwebkit2gtk-4.0-dev", SystemPackage: true, Library: true},
		},
		"gcc": []*Package{
			{Name: "build-essential", SystemPackage: true},
		},
		"pkg-config": []*Package{
			{Name: "pkg-config", SystemPackage: true},
		},
		"npm": []*Package{
			{Name: "npm", SystemPackage: true},
		},
		"docker": []*Package{
			{Name: "docker.io", SystemPackage: true, Optional: true},
		},
	}
}
```

Let's assume that in our linux distro, `libgtk-3` is packaged under the name `lib-gtk3-dev`.
We could add support for this by adding the following line:

```go {5}
func (a *Apt) Packages() packagemap {
	return packagemap{
		"libgtk-3": []*Package{
			{Name: "libgtk-3-dev", SystemPackage: true, Library: true},
			{Name: "lib-gtk3-dev", SystemPackage: true, Library: true},
		},
		"libwebkit": []*Package{
			{Name: "libwebkit2gtk-4.0-dev", SystemPackage: true, Library: true},
		},
		"gcc": []*Package{
			{Name: "build-essential", SystemPackage: true},
		},
		"pkg-config": []*Package{
			{Name: "pkg-config", SystemPackage: true},
		},
		"npm": []*Package{
			{Name: "npm", SystemPackage: true},
		},
		"docker": []*Package{
			{Name: "docker.io", SystemPackage: true, Optional: true},
		},
	}
}
```

## Adding new package managers

To add a new package manager, perform the following steps:

- Create a new file in `v2/internal/system/packagemanager` called `<pm>.go`, where `<pm>` is the name of the package manager.
- Define a struct that conforms to the package manager interface defined in `pm.go`:

```go
type PackageManager interface {
	Name() string
	Packages() packagemap
	PackageInstalled(*Package) (bool, error)
	PackageAvailable(*Package) (bool, error)
	InstallCommand(*Package) string
}
```

- `Name()` should return the name of the package manager
- `Packages()` should return a `packagemap`, that provides candidate filenames for dependencies
- `PackageInstalled()` should return `true` if the given package is installed
- `PackageAvailable()` should return `true` if the given package is not installed but available for installation
- `InstallCommand()` should return the exact command to install the given package name

Take a look at the other package managers code to get an idea how this works.

:::info Remember

If you add support for a new package manager, don't forget to also update this page!

:::

## Runtime Dependencies

When distributing your Wails application, end users need the GTK3 and WebKit2GTK runtime libraries installed.
The package names vary by distribution:

| Distribution | GTK3 | WebKit2GTK | ABI | Installation Command |
|--------------|------|------------|-----|---------------------|
| Debian 12 / Ubuntu 22.04+ | libgtk-3-0 | libwebkit2gtk-4.1-0 | 4.1 | `apt install libgtk-3-0 libwebkit2gtk-4.1-0` |
| Debian 11 / Ubuntu 20.04 | libgtk-3-0 | libwebkit2gtk-4.0-37 | 4.0 | `apt install libgtk-3-0 libwebkit2gtk-4.0-37` |
| Fedora 40+ | gtk3 | webkit2gtk4.1 | 4.1 | `dnf install gtk3 webkit2gtk4.1` |
| RHEL / CentOS / AlmaLinux / Rocky 8-9 | gtk3 | webkit2gtk3 | 4.0 | `dnf install gtk3 webkit2gtk3` |
| openSUSE Leap / Tumbleweed | libgtk-3-0 | libwebkit2gtk-4_1-0 | 4.1 | `zypper install libgtk-3-0 libwebkit2gtk-4_1-0` |
| Arch Linux / Manjaro | gtk3 | webkit2gtk-4.1 | 4.1 | `pacman -S gtk3 webkit2gtk-4.1` |

### WebKit2GTK ABI Versions

WebKit2GTK has two ABI versions:
- **ABI 4.1** - Modern version, used by most current distributions
- **ABI 4.0** - Legacy version, required for older distributions (Debian 11, Ubuntu 20.04, RHEL/CentOS 8-9)

When building your application, use the appropriate build tag:
- `-tags webkit2_41` for distributions with ABI 4.1 (default for most modern distros)
- `-tags webkit2_40` for RHEL-based systems and older Debian/Ubuntu

### Notes

- openSUSE provides both WebKitGTK 4.0 and 4.1; use `libwebkit2gtk-4_1-0` for the modern ABI
- Fedora only has `webkit2gtk4.1` starting from version 40; earlier versions use 4.0
- On RHEL/AlmaLinux/Rocky/CentOS 8-9, `webkit2gtk3` corresponds to ABI 4.0; 4.1 is not available
- Arch Linux offers both `webkit2gtk` (4.0) and `webkit2gtk-4.1`; use the latter for modern ABI

## Packaging with nfpm

When creating Linux packages with [nfpm](https://nfpm.goreleaser.com/), you need to specify the correct dependencies for each distribution.

### For Debian 12 / Ubuntu 22.04+ / openSUSE / Arch Linux (ABI 4.1)

```yaml
depends:
  - libgtk-3-0
  - libwebkit2gtk-4.1-0
overrides:
  rpm:
    depends:
      - libgtk-3-0
      - libwebkit2gtk-4_1-0
  archlinux:
    depends:
      - gtk3
      - webkit2gtk-4.1
```

### For RHEL / CentOS / AlmaLinux / Rocky and older Debian/Ubuntu (ABI 4.0)

```yaml
depends:
  - gtk3
  - webkit2gtk3
overrides:
  deb:
    depends:
      - libgtk-3-0
      - libwebkit2gtk-4.0-37
  archlinux:
    depends:
      - gtk3
      - webkit2gtk
```

### For Fedora 40+

```yaml
depends:
  - gtk3
  - webkit2gtk4.1
```

:::tip

To support multiple distributions, you may need separate nfpm configuration files for different ABI versions.

:::