ZLS (Zig Language Server): instalação e Zig 0.17

O ZLS (Zig Language Server) é um servidor de linguagem comunitário que adiciona autocompletar, diagnósticos, navegação e formatação ao editor pelo protocolo LSP. Para configurar esse Zig LSP, instale uma versão compatível com seu compilador e conecte o editor ao executável zls. No VS Code, a extensão Zig Language pode gerenciar a instalação; no Neovim, use o cliente LSP. Para erros de compilação do projeto, configure também o build ao salvar — autocompletar funcionando não garante análise semântica completa.

Resposta curta: em outubro de 2026, o compilador estável é Zig 0.17.0, mas a última release estável do ZLS continua em 0.16.0. Se você precisa do Zig Language Server agora, o pareamento recomendado pelo próprio projeto é Zig 0.16.0 + ZLS 0.16.0. Quem atualizou só o compilador para 0.17 pode continuar com zig build e testes; o ZLS ainda aguarda integração com a nova separação make/configure do build system. No VS Code, a extensão oficial Zig Language normalmente instala Zig e ZLS sozinha — fixe as versões se o gerenciador automático puxar um par incompatível.

ZLS em 30 segundos

Zig 0.17 e ZLS: qual versão usar?

A dúvida mais comum depois do lançamento do Zig 0.17 é se dá para atualizar o compilador e manter o Zig LSP no editor. Em outubro de 2026 a resposta prática é:

O bloqueio está documentado no repositório zigtools/zls: após a separação do build system em fases make e configure, falta um protocolo estável para o language server. Até isso ser resolvido, misturar Zig 0.17 com ZLS 0.16 tende a gerar falha de build diagnostics, servidor que não sobe ou análise incompleta.

Na prática:

1. confirme zig version e zls --version;
2. se precisa de autocompletar e diagnósticos no editor, fixe 0.16.0 nos dois;
3. se o projeto já migrou para 0.17, continue com a toolchain e espere a release do ZLS — não trate a branch master como substituta estável;
4. no VS Code, se a extensão atualizar só um dos lados, pinne zig.path e zig.zls.path (ou a política de versão da extensão) para o par 0.16.

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
zls --version

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

1. para usar ZLS com toolchain estável, fique em Zig 0.16.0 + ZLS 0.16.0;
2. se zig version já mostra 0.17.0, saiba que ainda não há ZLS 0.17 estável — compile sem language server ou mantenha um segundo Zig 0.16 só para o editor;
3. para Zig dev/nightly, leia o aviso atual do README do ZLS antes de compilar a branch master;
4. ao atualizar Zig, atualize o ZLS junto somente quando existir release da mesma série;
5. 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 alerta falta de integração crítica com o build system do Zig atual e aponta a combinação 0.16.0 como caminho seguro no interim.

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

No VS Code, o caminho mais simples é instalar a extensão oficial Zig Language (ziglang.vscode-zig). Segundo a documentação do Zigtools para VS Code, a extensão instala e gerencia Zig e ZLS automaticamente — em muitos casos você não precisa baixar o binário zls à mão.

code --install-extension ziglang.vscode-zig

Confirme que o language server está ativo:

{
  "zig.zls.enabled": "on",
  "editor.formatOnSave": true,
  "[zig]": {
    "editor.defaultFormatter": "ziglang.vscode-zig"
  }
}

Só force caminhos locais quando quiser uma toolchain fixa (CI espelhada, nightly pinada ou binário fora do gerenciador da extensão):

{
  "zig.path": "/caminho/para/zig",
  "zig.zls.path": "/caminho/para/zls"
}

Abra a pasta do projeto (a raiz com build.zig), abra um arquivo .zig e teste Go to Definition. Se o servidor não iniciar, use View → Output, selecione o canal da extensão Zig / ZLS e confira o guia de logs do Zigtools.

Para tasks e debug, veja VS Code para Zig. Se o autocompletar sumir ou aparecerem diagnósticos falsos, 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.

ZLS autocompleta, mas não mostra erros de compilação?

Autocompletar e diagnósticos de build são recursos diferentes. O ZLS pode resolver símbolos sem detectar todos os erros de tipos ou de comptime. Segundo o guia oficial de build ao salvar, há duas formas de ativar os diagnósticos do compilador:

A recomendação do Zigtools é definir um step check. Ele permite obter erros sem emitir o executável quando o artefato de verificação não é instalado. Não basta criar um step vazio: ele precisa depender do artefato que analisa o código do projeto. O exemplo completo está no guia oficial; adapte módulos, dependências e targets ao seu build.zig.

Depois de configurar:

1. execute zig build check (ou zig build quando não houver check) e resolva erros no script de build;
2. reinicie o ZLS para ele reconhecer a alteração;
3. introduza temporariamente um erro em uma função usada pelo programa e salve o arquivo;
4. confira o diagnóstico no editor, remova o erro e salve novamente.

Por padrão, o ZLS tenta o equivalente a zig build check --watch; o teste manual acima confirma que o step funciona antes de investigar o cliente LSP. Se o comando passa, mas o editor não mostra o erro após salvar, consulte os logs do ZLS e confirme qual compilador o servidor está usando. Testes continuam separados: build ao salvar não substitui zig build test.

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 de sintaxe gera diagnóstico; para erros de compilação, ative o build ao salvar e salve o arquivo;
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.

Perguntas frequentes

O que é ZLS em Zig?

ZLS é uma implementação não oficial do Language Server Protocol para Zig. Ele conecta o compilador e a análise de código ao editor para oferecer autocompletar, diagnósticos, navegação, referências, renomeação, formatação e inlay hints.

O que é Zig LSP?

Zig LSP é a forma comum de se referir ao language server de Zig. Na prática, o cliente LSP do editor fala com o binário ZLS. ZLS, Zig Language Server e Zig LSP apontam para a mesma ferramenta.

Como instalar ZLS no VS Code?

Instale a extensão oficial Zig Language (ziglang.vscode-zig). Em configuração padrão, a própria extensão baixa e gerencia Zig e ZLS. Só configure zig.path ou zig.zls.path se quiser forçar caminhos locais.

ZLS e Zig precisam ter a mesma versão?

Eles precisam ser compatíveis. Em outubro de 2026, a release estável do ZLS ainda é 0.16.0: use Zig 0.16.0 com ZLS 0.16.0. Zig 0.17.0 já é a estável do compilador, mas não há ZLS 0.17 recomendado enquanto a integração com o novo build system não estiver pronta.

Posso usar ZLS com Zig 0.17?

Ainda não de forma recomendada. Prefira o par 0.16 para o editor, ou use Zig 0.17 só para zig build / zig test até sair a release compatível do language server.

ZLS substitui zig build?

Não. O ZLS melhora o feedback no editor e pode rodar diagnósticos ao salvar, mas a validação do projeto continua sendo zig build e zig build test.

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.