Instalação
Instale o Wails e deixe-o pronto para criar aplicativos
Instalação rápida (5 minutos)
Instalação passo a passo
Instalar o Go (obrigatório)
O Wails requer o Go 1.25 ou posterior.
Baixe o instalador do Windows em go.dev/dl e execute-o.
Verifique a instalação:
go version # Should show 1.25 or later
Verifique o PATH:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
Se estiver vazio, adicione C:\Users\YourName\go\bin ao PATH.
Opção 1: instalador oficial
Baixe o instalador do macOS (arquivo .pkg) em go.dev/dl e execute-o.
Opção 2: Homebrew
brew install go
Verifique a instalação:
go version # Should show 1.25 or later
echo $PATH | grep go/bin # Should show ~/go/bin
Se ~/go/bin não estiver no PATH, adicione-o a ~/.zshrc ou ~/.bash_profile:
export PATH=$PATH:~/go/bin
Opção 1: arquivo tar oficial
Baixe o arquivo tar para Linux em go.dev/dl e, em seguida:
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
Adicione ao PATH (adicione a ~/.bashrc ou ~/.zshrc):
export PATH=$PATH:/usr/local/go/bin:~/go/bin
source ~/.bashrc # Reload
Verifique:
go version
echo $PATH | grep go/bin
Instalar as dependências da plataforma
Runtime do WebView2 (geralmente pré-instalado)
O Windows 10/11 inclui o WebView2 por padrão. Se ele não estiver instalado:
- Baixe-o da Microsoft
- Ou execute
wails3 doctormais tarde — ele orientará você
Pronto! Nenhuma outra dependência é necessária.
Ferramentas de linha de comando do Xcode (obrigatórias)
xcode-select --install
Clique em “Instalar” na caixa de diálogo exibida.
Verifique:
xcode-select -p # Should show /Library/Developer/CommandLineTools
Pronto! O macOS inclui o WebKit por padrão.
Ferramentas de compilação e WebKit
Requer Ubuntu 24.04+ ou Debian 13+ para a pilha GTK4 padrão.
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
Adicione a shell.nix ou devShell:
buildInputs = with pkgs; [ webkitgtk_6_0 gtk4 pkg-config gcc ];Execute wails3 doctor após instalar o Wails — ele mostrará os pacotes exatos necessários para sua distribuição.
Instalar a CLI do Wails
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
Isso instala o comando wails3 em ~/go/bin (ou %USERPROFILE%\go\bin no Windows).
Executar o assistente de configuração (recomendado)
wails3 setup
O assistente de configuração verificará suas dependências, ajudará a instalar as que estiverem ausentes e configurará os padrões do projeto.
Verificar a instalação
wails3 doctor
Saída esperada (ou semelhante):
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!Instalar o npm (opcional, mas recomendado)
A maioria dos modelos do Wails usa o npm como ferramenta de frontend.
Opção 1: instalador oficial Baixe em nodejs.org
Opção 2: Homebrew
brew install node
Verifique:
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
Verifique:
npm --version
Solução de problemas
Comando wails3 não encontrado
Causa: ~/go/bin (ou %USERPROFILE%\go\bin) não está no seu PATH.
Solução:
- Abra “Variáveis de Ambiente” (pesquise no menu Iniciar)
- Em “Variáveis de usuário”, localize
Path - Clique em “Editar” → “Novo”
- Adicione:
C:\Users\YourName\go\bin(substituaYourName) - Clique em “OK” em todas as caixas de diálogo
- Reinicie o terminal
Verifique:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
Adicione a ~/.zshrc (macOS) ou ~/.bashrc (Linux):
export PATH=$PATH:~/go/bin
Recarregue:
source ~/.zshrc # or ~/.bashrc
Verifique:
echo $PATH | grep go/bin
wails3 version
wails3 doctor informa que há dependências ausentes
Linux: a saída informa exatamente quais pacotes devem ser instalados. Exemplo:
❌ webkit2gtk not found
Install with: sudo apt install libwebkit2gtk-4.1-devWindows: se o WebView2 estiver ausente:
- Baixe da Microsoft
- Ou ele será instalado automaticamente quando você executar seu primeiro aplicativo
macOS: se as ferramentas do Xcode estiverem ausentes:
xcode-select --install
Versão do Go muito antiga
O Wails v3 requer o Go 1.25 ou posterior. Se você tiver uma versão mais antiga:
Baixe a versão mais recente em go.dev/dl e reinstale.
Baixe o tarball mais recente em 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 (mais recente)
Quer usar o código mais recente da ramificação principal de desenvolvimento? Isso dá acesso a novos recursos e correções antes do lançamento, mas traz o risco de bugs e alterações incompatíveis. Recomendado apenas para colaboradores ou para 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óximas etapas
Instalação concluída! Seu sistema está pronto para desenvolver com o Wails.
Crie um aplicativo funcional em 10 minutos.
Veja o que está disponível por padrão.
wails3 init -l # List templates
Está com problemas? Pergunte no Discord ou abra uma issue.