Installation
Quick Install (5 Minutes)
Step-by-Step Installation
Install Go (Required)
Wails requires Go 1.25 or later.
Download the Windows installer from go.dev/dl and run it.
Verify installation:
go version # Should show 1.25 or later
Check PATH:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
If empty, add C:\Users\YourName\go\bin to your PATH.
Option 1: Official Installer
Download the macOS installer (.pkg file) from go.dev/dl and run it.
Option 2: Homebrew
brew install go
Verify installation:
go version # Should show 1.25 or later
echo $PATH | grep go/bin # Should show ~/go/bin
If ~/go/bin isn’t in PATH, add to ~/.zshrc or ~/.bash_profile:
export PATH=$PATH:~/go/bin
Option 1: Official Tarball
Download the Linux tarball from go.dev/dl, then:
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
Option 2: Package Manager
# Ubuntu/Debian
sudo apt install golang-go
# Fedora
sudo dnf install golang
# Arch
sudo pacman -S go
Add to PATH (add to ~/.bashrc or ~/.zshrc):
export PATH=$PATH:/usr/local/go/bin:~/go/bin
source ~/.bashrc # Reload
Verify:
go version
echo $PATH | grep go/bin
Install Platform Dependencies
WebView2 Runtime (usually pre-installed)
Windows 10/11 includes WebView2 by default. If missing:
- Download from [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/)
- Or run `wails3 doctor` later—it will guide you
**That's it!** No other dependencies needed.
Xcode Command Line Tools (required)
xcode-select --install
Click “Install” in the dialog that appears.
Verify:
xcode-select -p # Should show /Library/Developer/CommandLineTools
That’s it! macOS includes WebKit by default.
Build tools and WebKit
Requires Ubuntu 24.04+ or Debian 13+ for the default GTK4 stack.
sudo apt update
sudo apt install build-essential pkg-config libgtk-4-dev libwebkitgtk-6.0-dev
sudo dnf install gcc pkg-config gtk4-devel webkitgtk6.0-devel
sudo pacman -S base-devel gtk4 webkitgtk-6.0
sudo zypper install gcc pkg-config gtk4-devel webkitgtk-6_0-devel
sudo emerge --ask net-libs/webkit-gtk:6
Add to your shell.nix or devShell:
buildInputs = with pkgs; [ webkitgtk_6_0 gtk4 pkg-config gcc ];Run wails3 doctor after installing Wails—it will show the exact packages needed for your distribution.
Install Wails CLI
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
This installs the wails3 command to ~/go/bin (or %USERPROFILE%\go\bin on Windows).
Run Setup Wizard (Recommended)
wails3 setup
The setup wizard will check your dependencies, help install missing ones, and configure project defaults.
Verify Installation
wails3 doctor
Expected output (or similar):
Wails (v3.0.0-dev) Wails Doctor
# System
┌──────────────────────────────────────────────────┐
| Name | MacOS |
| Version | 26.0 |
| ID | 25A354 |
| Branding | MacOS 26.0 |
| Platform | darwin |
| Architecture | arm64 |
| Apple Silicon | true |
| CPU | Apple M2 Pro |
| CPU 1 | Apple M2 Pro |
| CPU 2 | Apple M2 Pro |
| GPU | 16 cores, Metal Support: Metal 4 |
| Memory | 16 GB |
└──────────────────────────────────────────────────┘
# Build Environment
┌─────────────┬─────────────────┐
| Wails CLI | Your installed version |
| Go Version | go1.25.0 |
└─────────────┴─────────────────┘
# Dependencies
┌─────────────────┬─────────────────────────────────────────────────┐
| npm | 11.6.2 |
| *NSIS | Not Installed. Install with `brew install...`. |
| Xcode cli tools | 2412 |
└─────────────────┴─────────────────────────────────────────────────┘
# Checking for issues
SUCCESS No issues found
# Diagnosis
SUCCESS Your system is ready for Wails development!Install npm (Optional but Recommended)
Most Wails templates use npm for frontend tooling.
Option 1: Official Installer Download from nodejs.org
Option 2: Homebrew
brew install node
Verify:
npm --version
Option 1: NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs # Ubuntu/Debian
Option 2: Package Manager
sudo dnf install nodejs # Fedora
sudo pacman -S nodejs npm # Arch
Verify:
npm --version
Troubleshooting
wails3 command not found
Cause: ~/go/bin (or %USERPROFILE%\go\bin) isn’t in your PATH.
Solution:
- Open “Environment Variables” (search in Start menu)
- Under “User variables”, find
Path - Click “Edit” → “New”
- Add:
C:\Users\YourName\go\bin(replaceYourName) - Click “OK” on all dialogs
- Restart your terminal
Verify:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
Add to ~/.zshrc (macOS) or ~/.bashrc (Linux):
export PATH=$PATH:~/go/bin
Reload:
source ~/.zshrc # or ~/.bashrc
Verify:
echo $PATH | grep go/bin
wails3 version
wails3 doctor reports missing dependencies
Linux: The output tells you exactly which packages to install. Example:
❌ webkit2gtk not found
Install with: sudo apt install libwebkit2gtk-4.1-devWindows: If WebView2 is missing:
- Download from Microsoft
- Or it will be installed automatically when you run your first app
macOS: If Xcode tools are missing:
xcode-select --install
Go version too old
Wails v3 requires Go 1.25+. If you have an older version:
Download the latest from go.dev/dl and reinstall.
Download the latest tarball from go.dev/dl, then:
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
Development Version (Bleeding Edge)
Want to use the absolute latest code from the main development branch? This gives you access to new features and fixes before they’re released, but comes with the risk of bugs and breaking changes. Only recommended for contributors or those who need to test upcoming features.
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install
Next Steps
Installation Complete! Your system is ready for Wails development.
Create a working application in 10 minutes.
See what’s available out of the box.
wails3 init -l # List templates
Having issues? Ask in Discord or open an issue.