---
title: "Atualizar Versão do Zig — Migrar entre Versões"
url: "https://ziglang.com.br/troubleshooting/atualizar-vers%C3%A3o-do-zig-migrar-entre-vers%C3%B5es/"
markdown_url: "https://ziglang.com.br/troubleshooting/atualizar-vers%C3%A3o-do-zig-migrar-entre-vers%C3%B5es.MD"
description: "Guia para atualizar a versão do Zig de forma segura. Changelog, breaking changes, migrar build.zig, atualizar dependências e resolver incompatibilidades."
date: "2026-02-21"
author: "Zig Brasil"
---

# Atualizar Versão do Zig — Migrar entre Versões

Guia para atualizar a versão do Zig de forma segura. Changelog, breaking changes, migrar build.zig, atualizar dependências e resolver incompatibilidades.


# Atualizar Versão do Zig — Migrar entre Versões

Zig ainda está em desenvolvimento ativo e atualizações podem incluir breaking changes. Este guia ajuda a atualizar de forma segura e resolver incompatibilidades.

## Processo de Atualização Seguro

### Passo 1: Verificar a Versão Atual

```bash
# Versão instalada
zig version

# Versão usada no projeto (se documentada)
cat .zig-version 2>/dev/null
```

### Passo 2: Ler o Changelog

Antes de atualizar, **sempre leia o changelog**:

- **Release notes:** [ziglang.org/download](https://ziglang.org/download/)
- **GitHub releases:** [github.com/ziglang/zig/releases](https://github.com/ziglang/zig/releases)
- **Breaking changes:** Listados explicitamente nas release notes

### Passo 3: Atualizar em Branch Separada

```bash
# Criar branch para a atualização
git checkout -b atualizar-zig-0.14

# Instalar nova versão
# macOS
brew upgrade zig

# Linux — baixar nova versão
wget https://ziglang.org/download/0.14.0/zig-linux-x86_64-0.14.0.tar.xz
tar xf zig-linux-x86_64-0.14.0.tar.xz

# Windows
scoop update zig
```

### Passo 4: Tentar Compilar

```bash
# Primeiro, tentar compilar
zig build 2>&1

# O compilador indicará o que precisa mudar
# Corrigir cada erro um por um
```

### Passo 5: Rodar Testes

```bash
# Rodar todos os testes
zig build test

# Testar em todos os targets usados
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=x86_64-windows
```

## Mudanças Comuns entre Versões

### Mudanças de API do Build System

O build system muda frequentemente. Padrões comuns de migração:

```zig
// ANTIGO (versões anteriores):
// exe.addPackagePath("mod", "src/mod.zig");

// NOVO:
exe.root_module.addImport("mod", b.addModule(.{
    .name = "mod",
    .root_source_file = b.path("src/mod.zig"),
}));
```

```zig
// ANTIGO:
// .root_source_file = .{ .path = "src/main.zig" },

// NOVO:
.root_source_file = b.path("src/main.zig"),
```

### Mudanças de Sintaxe da Linguagem

```zig
// Mudanças em builtins (exemplos genéricos)
// Builtins podem ser renomeados ou ter assinatura alterada

// Sempre consulte a documentação da nova versão:
// https://ziglang.org/documentation/master/
```

### Mudanças na Standard Library

```zig
// Funções podem ser movidas, renomeadas ou removidas
// Exemplo genérico:
// ANTIGO: std.mem.toSlice(u8, ptr)
// NOVO: std.mem.span(ptr)

// ANTIGO: std.fmt.bufPrint(...)
// NOVO: std.fmt.bufPrint(...) // mesma função, parâmetros podem mudar
```

## Atualizar Dependências

```bash
# Verificar se dependências suportam a nova versão do Zig
# Consultar o repositório de cada dependência

# Atualizar hash se a dependência tem versão nova
zig fetch --save https://github.com/user/lib/archive/v2.0.tar.gz

# Se a dependência não suporta a nova versão:
# 1. Abrir issue no repositório da dependência
# 2. Usar versão de desenvolvimento (branch main)
# 3. Fazer fork e corrigir
```

## Atualizar o ZLS

Quando atualiza o Zig, **sempre atualize o ZLS** também:

```bash
# macOS
brew upgrade zls

# Ou baixar do GitHub
# https://github.com/zigtools/zls/releases

# Verificar compatibilidade
zig version
zls --version
# Devem ser versões compatíveis
```

## Atualizar o CI

```yaml
# .github/workflows/ci.yml
# Atualizar a versão no CI
- uses: goto-bus-stop/setup-zig@v2
  with:
    version: 0.14.0  # Nova versão
```

## Lidar com Breaking Changes

### Estratégia 1: Compilação Condicional

```zig
const builtin = @import("builtin");

// Código compatível com múltiplas versões (quando necessário)
const zig_version = builtin.zig_version;
```

### Estratégia 2: Correção Iterativa

```bash
# Corrigir um erro de cada vez
zig build 2>&1 | head -5
# Corrigir o primeiro erro
# Repetir até compilar limpo
```

### Estratégia 3: Consultar o Compilador

```bash
# O compilador frequentemente sugere a correção
zig build 2>&1
# Muitas mensagens de erro incluem "note: " com a sugestão

# Usar zig fmt para corrigir mudanças de formatação
zig fmt src/
```

## Rollback se Necessário

```bash
# Se a atualização causa muitos problemas:
git checkout main  # Voltar para branch estável

# Reinstalar versão anterior
# Manter múltiplas versões do Zig disponíveis
# Criar aliases: zig-0.13, zig-0.14, etc.
```

## Documentar a Versão do Zig

```bash
# Criar arquivo .zig-version no projeto
echo "0.14.0" > .zig-version

# Documentar no README
# ## Requisitos
# - Zig >= 0.14.0
```

```zig
// No build.zig.zon — minimum_zig_version
.{
    .name = "meu-projeto",
    .version = "1.0.0",
    .minimum_zig_version = "0.14.0",
    .paths = .{"."},
}
```

## Checklist de Atualização

1. Ler changelog e breaking changes
2. Criar branch separada
3. Instalar nova versão do Zig
4. Tentar compilar e corrigir erros
5. Atualizar dependências
6. Rodar todos os testes
7. Atualizar ZLS
8. Atualizar CI/CD
9. Testar em todos os targets
10. Documentar a nova versão no projeto
11. Merge para main quando estável

## Veja Também

- [FAQ Build System](/faq/faq-build-system/) — Configuração de build
- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Resolver erros do build
- [Falha em Dependências](/troubleshooting/zig-dependencia-falha/) — Atualizar dependências
- [CI Falha](/troubleshooting/zig-ci-falha/) — Atualizar CI
- [FAQ Produção](/faq/faq-producao/) — Estabilidade em produção