Instalação

Instalação Rápida (5 minutos)

TL;DR - Para desenvolvedores experientes

# Instale o Go 1.25+ e depois:
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 doctor  # Verificar instalação

Se o wails3 doctor passar, você está pronto. Pule para o Primeiro App →

Instalação Passo a Passo

1. Instalar o Go (necessário)

   O Wails requer Go 1.25 ou superior.

   Windows

   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.

   macOS

   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

   Linux

   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

2. Instalar dependências de plataforma

   Windows

   WebView2 Runtime (geralmente pré-instalado)

   O Windows 10/11 vem com WebView2 por padrão. Se estiver faltando:

   • Baixe da Microsoft
   • Ou execute wails3 doctor depois e ele irá guiá-lo

   Isso é tudo! Nenhuma outra dependência é necessária.

   Dica de desempenho para Windows 11

   Considere usar Dev Drive para armazenar seu projeto. O Dev Drive é otimizado para cargas de trabalho de desenvolvimento e pode melhorar os tempos de compilação e velocidades de acesso ao disco em até 30%.

   macOS

   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.

   Linux

   Ferramentas de build e WebKit

   Versão mínima da distribuição

   O Wails v3 requer WebKitGTK 4.1 (usando libsoup3). Versões mais antigas — Ubuntu 20.04, Debian 11, RHEL 8/9 e derivados — que fornecem apenas 4.0 não são suportadas.

   Ubuntu/Debian

   Requer Ubuntu 22.04+ ou Debian 12+.

   sudo apt update
   sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev

   Fedora

   sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel

   Arch

   sudo pacman -S base-devel gtk3 webkit2gtk-4.1

   openSUSE

   sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel

   Gentoo

   sudo emerge --ask net-libs/webkit-gtk:4.1

   NixOS

   Adicione ao seu shell.nix ou devShell:

   buildInputs = with pkgs; [ webkitgtk_4_1 gtk3 pkg-config gcc ];

   Outros

   Após instalar o Wails, execute wails3 doctor. Ele mostrará os pacotes exatos necessários para sua distribuição.

   Opcional: Suporte ao GTK4

   O Wails também tem suporte experimental a GTK4 / WebKitGTK 6.0. Se quiser compilar com GTK4, instale as dependências adicionais para sua distribuição e compile com wails3 build -tags gtk4. Veja Linux Packaging - GTK4 para detalhes.

3. 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).

4. 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   | v3.0.0-alpha.40 |
   | 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!

   Comando wails3 não encontrado

   ~/go/bin não está no PATH. Consulte o Passo 1 acima para corrigir e reinicie o terminal.

5. Instalar npm (opcional, mas recomendado)

   A maioria dos templates Wails usa npm para ferramentas de frontend.

   Windows

   Baixe de nodejs.org e execute o instalador.

   Verificar:

   npm --version

   macOS

   Opção 1: Instalador oficial Baixe de nodejs.org

   Opção 2: Homebrew

   brew install node

   Verificar:

   npm --version

   Linux

   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

   Gerenciadores de pacotes alternativos

   Prefere pnpm, yarn ou bun? Sem problema! Atualize o Taskfile.yml do seu projeto para usar a ferramenta de sua preferência.

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:

Windows

1. Abra “Variáveis de Ambiente” (pesquise no menu Iniciar)
2. Encontre Path em “Variáveis do usuário”
3. Clique em “Editar” → “Novo”
4. Adicione: C:\Users\SeuNome\go\bin (substitua SeuNome)
5. Clique em “OK” em todas as caixas de diálogo
6. Reinicie o terminal

Verificar:

$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }

macOS/Linux

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-dev

Windows: 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:

Windows/macOS

Baixe a versão mais recente de go.dev/dl e reinstale.

Linux

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

Versão de Desenvolvimento

• Pode conter bugs ou mudanças que quebram compatibilidade
• Projetos criados usarão diretiva replace apontando para o Wails local
• Recomendado apenas para colaboradores ou teste de novos recursos

Próximos Passos

Instalação concluída! Seu sistema está pronto para o desenvolvimento com Wails.

Construa seu primeiro app

Crie um aplicativo funcional em 10 minutos.

Tutorial do Primeiro App →

Explore os templates

Veja o que está disponível por padrão.

wails3 init -l  # Listar templates

---

Tendo problemas? Pergunte no Discord ou abra uma issue.