ZLS: Instalar e Configurar o Zig Language Server

O ZLS é o Zig Language Server: uma implementação não oficial do protocolo LSP que adiciona autocompletar, diagnósticos, hover, navegação para definições, referências, renomeação, formatação e inlay hints ao seu editor. Para começar, instale uma versão do ZLS compatível com a sua versão do Zig, confirme com zls --version e configure o editor para executar o binário zls.

Resposta curta: se você procura “ZLS”, instale a release correspondente à série do seu compilador Zig. Em agosto de 2026, a release estável mais recente do ZLS é a 0.16.0. A branch master acompanha Zig de desenvolvimento e não é a escolha mais segura para uma toolchain estável.

ZLS em 30 segundos

O que é o ZLS e como ele funciona

O ZLS é um processo separado que conversa com o editor pelo Language Server Protocol. O editor envia informações sobre arquivos abertos, alterações e ações do usuário; o ZLS responde com itens de autocompletar, localização de símbolos, diagnósticos e outras informações sem exigir que cada editor implemente um analisador próprio de Zig.

Na prática, a arquitetura fica assim:

VS Code / Neovim / Emacs / Helix
              ↓ LSP
             ZLS
              ↓
   código Zig + build.zig + toolchain Zig

Isso explica uma distinção importante: um aviso no editor e o resultado de zig build podem divergir. O ZLS melhora o feedback durante a edição, mas a autoridade final sobre a compilação é o compilador usado pelo projeto.

Os recursos documentados pelo projeto incluem:

• autocompletar e placeholders de argumentos;
• hover com tipos e documentação;
• diagnósticos e build ao salvar opcional;
• ir para definição ou declaração;
• símbolos do documento e do workspace;
• encontrar referências e renomear símbolos;
• formatação baseada em zig fmt;
• semantic highlighting;
• inlay hints;
• code actions.

O suporte a análise semântica e a comptime continua evoluindo. Portanto, construções muito dinâmicas podem produzir sugestões incompletas mesmo quando o código compila corretamente.

Antes de instalar: confira a compatibilidade

Primeiro descubra a versão do compilador:

zig version

Depois escolha uma release compatível do ZLS. A recomendação prática é:

1. para Zig estável, use a release do ZLS da mesma série;
2. para Zig dev/nightly, consulte qual revisão a branch principal do ZLS está acompanhando;
3. ao atualizar Zig, atualize o ZLS junto;
4. em equipes, fixe as versões no README, no gerenciador de toolchain ou no ambiente de desenvolvimento.

Não presuma que compilar a branch master com qualquer Zig instalado funcionará. O README oficial informa explicitamente qual build de desenvolvimento é exigida naquele momento.

Como instalar o ZLS

A fonte mais segura para instruções e binários é a documentação oficial do Zigtools e a página de releases do ZLS no GitHub.

Opção 1: binário oficial da release

Baixe o arquivo correspondente ao sistema e à arquitetura. Os nomes seguem formatos como:

zls-x86_64-linux.tar.xz
zls-aarch64-macos.tar.xz
zls-x86_64-windows.zip

No Linux x86_64, por exemplo:

ZLS_VERSION="0.16.0"
curl -LO "https://github.com/zigtools/zls/releases/download/${ZLS_VERSION}/zls-x86_64-linux.tar.xz"
tar -xf "zls-x86_64-linux.tar.xz"
mkdir -p "$HOME/.local/bin"
mv zls "$HOME/.local/bin/zls"

Garanta que ~/.local/bin esteja no PATH e teste:

zls --version
which zls

No Windows, extraia zls.exe para um diretório permanente e adicione esse diretório ao PATH. No macOS, escolha aarch64 para Apple Silicon ou x86_64 para Macs Intel.

Opção 2: gerenciador de pacotes

Alguns sistemas distribuem o ZLS diretamente:

# macOS ou Linux com Homebrew
brew install zls

# Arch Linux
sudo pacman -S zls

# Nix
nix profile install nixpkgs#zls

Essa opção é conveniente, mas confira se o pacote acompanha a série do Zig que você usa. Um repositório do sistema pode atualizar Zig e ZLS em momentos diferentes.

Opção 3: compilar a partir do código-fonte

Use esta opção quando você precisa acompanhar uma versão de desenvolvimento ou testar uma correção ainda não publicada:

git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe
./zig-out/bin/zls --version

O binário resultante fica em zig-out/bin/zls. Antes de compilar, leia o README do repositório e confirme a versão exata de Zig exigida pela branch atual.

Configurar ZLS no VS Code

Instale a extensão Zig Language, de identificador ziglang.vscode-zig:

code --install-extension ziglang.vscode-zig

Se zig e zls já estiverem no PATH, a extensão normalmente consegue encontrá-los. Quando precisar informar caminhos explícitos, abra o settings.json e use:

{
  "zig.path": "/caminho/para/zig",
  "zig.zls.path": "/caminho/para/zls",
  "editor.formatOnSave": true,
  "[zig]": {
    "editor.defaultFormatter": "ziglang.vscode-zig"
  }
}

Depois abra um arquivo .zig, posicione o cursor sobre um símbolo e teste Go to Definition. Se o servidor não iniciar, abra View → Output e selecione o canal da extensão Zig ou do language server.

Para uma configuração completa de tasks e debug, use o guia de VS Code para Zig. Se o editor exibir erros falsos ou perder o autocompletar, consulte problemas comuns de VS Code e ZLS.

Configurar ZLS no Neovim

Em versões atuais do Neovim com nvim-lspconfig, uma configuração mínima é:

vim.lsp.config("zls", {
  cmd = { "zls" },
  filetypes = { "zig", "zon" },
  root_markers = { "build.zig", "build.zig.zon", ".git" },
})

vim.lsp.enable("zls")

Se sua configuração ainda usa a API anterior do lspconfig, consulte a documentação da versão instalada antes de copiar snippets antigos. A interface do cliente LSP do Neovim evolui, enquanto o executável chamado continua sendo zls.

Para verificar o estado do servidor dentro do Neovim, use :checkhealth vim.lsp e observe o log em caso de falha. Confirme também no shell iniciado pelo editor:

which zig
which zls
zig version
zls --version

Configurar no Emacs e Helix

Emacs com Eglot

No Emacs 29 ou mais recente, associe o modo Zig ao comando zls:

(add-to-list 'eglot-server-programs '(zig-mode . ("zls")))
(add-hook 'zig-mode-hook #'eglot-ensure)

Se você usa zig-ts-mode, ajuste o símbolo do modo na associação. Rode M-x eglot para iniciar manualmente e consulte o buffer de eventos do Eglot quando houver erro.

Helix

O Helix costuma reconhecer o ZLS quando o binário está no PATH. Verifique com:

hx --health zig

Se precisar sobrescrever a configuração, use languages.toml:

[language-server.zls]
command = "zls"

[[language]]
name = "zig"
language-servers = ["zls"]

Para outros clientes, veja também o comparativo de plugins e editores para Zig.

Configuração do próprio ZLS

O ZLS oferece opções para snippets, build ao salvar, semantic tokens, inlay hints e caminhos da toolchain. Evite copiar um zls.json grande de um tutorial antigo: opções podem ser removidas ou ter o padrão alterado.

Um arquivo pequeno e intencional é mais fácil de manter:

{
  "enable_snippets": true,
  "enable_build_on_save": true,
  "semantic_tokens": "full",
  "warn_style": false,
  "zig_exe_path": "/caminho/para/zig"
}

Principais opções atuais:

Consulte o schema.json oficial antes de adicionar opções. Por exemplo, skip_std_references ainda pode aparecer em configurações antigas, mas o schema atual informa que a opção não é mais usada.

Como validar a instalação

Faça um teste mínimo em um diretório novo:

mkdir teste-zls
cd teste-zls
zig init
zls --version
zig build

Abra o diretório inteiro no editor, não apenas src/main.zig. Isso permite que o servidor encontre build.zig, build.zig.zon e a raiz do workspace.

Em seguida, confirme quatro sinais:

1. hover mostra o tipo de um símbolo;
2. ir para definição funciona sobre uma função;
3. um erro proposital gera diagnóstico;
4. zig build continua passando depois de remover o erro.

ZLS não funciona: checklist de diagnóstico

1. O comando não é encontrado

which zls      # Linux/macOS
where.exe zls  # Windows

Se o terminal encontra o binário, mas o editor não, o editor pode ter sido aberto antes da alteração do PATH. Reinicie-o ou configure o caminho absoluto.

2. As versões são incompatíveis

zig version
zls --version

Instale a release compatível ou volte Zig e ZLS para a combinação usada pelo projeto. Esse é o primeiro ponto a verificar após uma atualização de toolchain.

3. O workspace foi aberto na pasta errada

Abra a raiz que contém build.zig ou .git. Sem uma raiz adequada, dependências e módulos podem não ser resolvidos como esperado.

4. O build está quebrado

zig build
zig build test

Corrija primeiro os erros reproduzíveis no terminal. Reiniciar o language server não resolve um build.zig inválido.

5. O editor mostra diagnóstico falso

Compare o aviso com o compilador, reinicie o cliente LSP e verifique o log. Se o caso depender de comptime complexo, reduza-o a um exemplo mínimo antes de abrir uma issue no projeto ZLS.

6. A configuração contém opções obsoletas

Remova temporariamente o arquivo de configuração personalizado e teste com os padrões. Reintroduza uma opção por vez, sempre conferindo o schema da versão instalada.

Próximos passos

Com ZLS funcionando, complete o ambiente com instalação do Zig, ferramentas de debug e o sistema de build do Zig. A combinação de feedback rápido no editor com zig build e testes no terminal oferece um fluxo produtivo sem confundir conveniência de IDE com validação real do programa.

Para documentação primária, acompanhe o repositório zigtools/zls, o guia de instalação do Zigtools e as notas da release que você pretende instalar.