Instalação
Instalação Rápida (5 minutos)
Instalação Passo a Passo
Instalar o Go (necessário)
O Wails requer Go 1.25 ou superior.
Baixe e execute o instalador Windows em go.dev/dl.
Verificar instalação:
go version # Deve mostrar 1.25+
Verificar PATH:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
Se estiver vazio, adicione C:\Users\SeuNome\go\bin ao PATH.
Opção 1: Instalador oficial
Baixe e execute o instalador macOS (arquivo .pkg) em go.dev/dl.
Opção 2: Homebrew
brew install go
Verificar instalação:
go version # Deve mostrar 1.25+
echo $PATH | grep go/bin # Deve mostrar ~/go/bin
Se ~/go/bin não estiver no PATH, adicione ao ~/.zshrc ou ~/.bash_profile:
export PATH=$PATH:~/go/bin
Opção 1: Tarball oficial
Baixe o tarball Linux em go.dev/dl e depois:
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
Opção 2: Gerenciador de pacotes
# Ubuntu/Debian
sudo apt install golang-go
# Fedora
sudo dnf install golang
# Arch
sudo pacman -S go
Adicionar ao PATH (adicione ao ~/.bashrc ou ~/.zshrc):
export PATH=$PATH:/usr/local/go/bin:~/go/bin
source ~/.bashrc # Recarregar
Verificar:
go version
echo $PATH | grep go/bin
Instalar dependências de plataforma
WebView2 Runtime (geralmente pré-instalado)
O Windows 10/11 vem com WebView2 por padrão. Se estiver faltando:
- Baixe da [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/)
- Ou execute `wails3 doctor` depois e ele irá guiá-lo
**Isso é tudo!** Nenhuma outra dependência é necessária.
Xcode Command Line Tools (necessário)
xcode-select --install
Clique em “Instalar” na caixa de diálogo que aparecer.
Verificar:
xcode-select -p # Deve mostrar /Library/Developer/CommandLineTools
Isso é tudo! O macOS vem com WebKit embutido.
Ferramentas de build e WebKit
Requer Ubuntu 22.04+ ou Debian 12+.
sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel
sudo pacman -S base-devel gtk3 webkit2gtk-4.1
sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel
sudo emerge --ask net-libs/webkit-gtk:4.1
Adicione ao seu shell.nix ou devShell:
buildInputs = with pkgs; [ webkitgtk_4_1 gtk3 pkg-config gcc ];Após instalar o Wails, execute wails3 doctor. Ele mostrará os pacotes exatos necessários para sua distribuição.
Instalar o Wails CLI
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
Isso instala o comando wails3 em ~/go/bin (ou %USERPROFILE%\go\bin no Windows).
Verificar instalação
wails3 doctor
Saída esperada (ou 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 | Sua versão instalada |
| Go Version | go1.24.6 |
└─────────────┴─────────────────┘
# 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!Instalar npm (opcional, mas recomendado)
A maioria dos templates Wails usa npm para ferramentas de frontend.
Opção 1: Instalador oficial Baixe de nodejs.org
Opção 2: Homebrew
brew install node
Verificar:
npm --version
Opção 1: NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs # Ubuntu/Debian
Opção 2: Gerenciador de pacotes
sudo dnf install nodejs # Fedora
sudo pacman -S nodejs npm # Arch
Verificar:
npm --version
Solução de Problemas
Comando wails3 não encontrado
Causa: ~/go/bin (ou %USERPROFILE%\go\bin no Windows) não está no PATH.
Solução:
- Abra “Variáveis de Ambiente” (pesquise no menu Iniciar)
- Encontre
Pathem “Variáveis do usuário” - Clique em “Editar” → “Novo”
- Adicione:
C:\Users\SeuNome\go\bin(substitua SeuNome) - Clique em “OK” em todas as caixas de diálogo
- Reinicie o terminal
Verificar:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
Adicione ao ~/.zshrc (macOS) ou ~/.bashrc (Linux):
export PATH=$PATH:~/go/bin
Recarregar:
source ~/.zshrc # ou ~/.bashrc
Verificar:
echo $PATH | grep go/bin
wails3 version
wails3 doctor relata dependências ausentes
Linux: A saída mostra exatamente quais pacotes instalar. Exemplo:
❌ webkit2gtk não encontrado
Instale com: sudo apt install libwebkit2gtk-4.1-devWindows: Se o WebView2 não for encontrado:
- Baixe da Microsoft
- Ou ele será instalado automaticamente na primeira execução do app
macOS: Se as ferramentas Xcode não forem encontradas:
xcode-select --install
Versão do Go muito antiga
O Wails v3 requer Go 1.25+. Se você tiver uma versão mais antiga:
Baixe a versão mais recente de go.dev/dl e reinstale.
Baixe o tarball mais recente de go.dev/dl e depois:
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
Versão de Desenvolvimento (Bleeding Edge)
Quer usar o código mais recente do branch de desenvolvimento principal? Isso permite acesso a novos recursos e correções antes do lançamento, mas vem com o risco de bugs e mudanças que quebram compatibilidade. Recomendado apenas para colaboradores ou quem precisa testar recursos futuros.
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install
Próximos Passos
Instalação concluída! Seu sistema está pronto para o desenvolvimento com Wails.
Crie um aplicativo funcional em 10 minutos.
Veja o que está disponível por padrão.
wails3 init -l # Listar templates
Tendo problemas? Pergunte no Discord ou abra uma issue.