Como Instalar Zig no macOS

Este guia cobre a instalação do compilador Zig no macOS, com suporte tanto para processadores Intel quanto Apple Silicon (M1, M2, M3, M4). Apresentamos três métodos: Homebrew (recomendado), MacPorts e download manual.

Para uma visão geral de todas as plataformas, consulte o guia completo de instalação. Se você está aprendendo Zig, comece pela introdução ao Zig.

Método 1: Homebrew (Recomendado)

O Homebrew é o gerenciador de pacotes mais popular no macOS e a forma mais simples de instalar o Zig.

Pré-requisito: Instalar o Homebrew

Se você ainda não tem o Homebrew instalado:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Siga as instruções exibidas no terminal após a instalação.

Passo 1: Instalar o Zig

brew install zig

O Homebrew vai baixar, compilar (se necessário) e configurar o Zig automaticamente. O processo leva de 1 a 5 minutos dependendo da velocidade da sua conexão.

Passo 2: Verificar a Instalação

zig version

Saída esperada:

0.14.0

Passo 3: Testar com um Programa

Crie um arquivo hello.zig:

const std = @import("std");

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();
    try stdout.print("Zig funcionando no macOS!\n", .{});

    // Detectar a arquitetura do sistema
    const arch = @tagName(@import("builtin").cpu.arch);
    try stdout.print("Arquitetura: {s}\n", .{arch});
}

Execute:

zig run hello.zig

Em um Mac com Apple Silicon, a saída será:

Zig funcionando no macOS!
Arquitetura: aarch64

Atualizando o Zig via Homebrew

brew update
brew upgrade zig

Instalar uma Versão Específica

Para instalar a versão mais recente de desenvolvimento (HEAD):

brew install zig --HEAD

Nota: A versão HEAD é compilada do código-fonte e pode levar mais tempo para instalar.

Desinstalar via Homebrew

brew uninstall zig

Método 2: MacPorts

O MacPorts é uma alternativa ao Homebrew, popular em ambientes acadêmicos e corporativos.

Pré-requisito: Instalar o MacPorts

Baixe o instalador em macports.org/install.php e siga as instruções para sua versão do macOS.

Instalar o Zig

sudo port install zig

Verificar

zig version

Atualizar

sudo port selfupdate
sudo port upgrade zig

Desinstalar

sudo port uninstall zig

Método 3: Download Manual

O download manual é útil quando você precisa de uma versão específica do Zig ou quando não quer usar gerenciadores de pacotes.

Passo 1: Identificar sua Arquitetura

uname -m

arm64 — Apple Silicon (M1, M2, M3, M4)
x86_64 — Intel

Passo 2: Baixar o Zig

Para Apple Silicon (M1/M2/M3/M4):

curl -LO https://ziglang.org/download/0.14.0/zig-macos-aarch64-0.14.0.tar.xz

Para Intel:

curl -LO https://ziglang.org/download/0.14.0/zig-macos-x86_64-0.14.0.tar.xz

Passo 3: Extrair

Para Apple Silicon:

tar -xf zig-macos-aarch64-0.14.0.tar.xz

Para Intel:

tar -xf zig-macos-x86_64-0.14.0.tar.xz

Passo 4: Mover para um Diretório Permanente

sudo mv zig-macos-aarch64-0.14.0 /usr/local/zig

Passo 5: Adicionar ao PATH

Para Zsh (padrão no macOS moderno):

echo 'export PATH="/usr/local/zig:$PATH"' >> ~/.zshrc
source ~/.zshrc

Para Bash:

echo 'export PATH="/usr/local/zig:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Passo 6: Verificar

zig version

macOS Gatekeeper e Segurança

Ao baixar o Zig manualmente, o macOS pode bloquear a execução por causa do Gatekeeper (sistema de segurança). Se você receber a mensagem “zig cannot be opened because the developer cannot be verified”, siga estes passos:

Opção 1: Via Preferências do Sistema

Abra Ajustes do Sistema (System Settings)
Vá em Privacidade e Segurança (Privacy & Security)
Role até encontrar a mensagem sobre o Zig
Clique em Permitir Mesmo Assim (Allow Anyway)

Opção 2: Via Terminal

# Remover o atributo de quarentena de todo o diretório do Zig
xattr -r -d com.apple.quarantine /usr/local/zig

Opção 3: Usando spctl

sudo spctl --master-disable
# Execute o zig uma vez
zig version
# Reative o Gatekeeper
sudo spctl --master-enable

Recomendação: A Opção 2 é a mais segura, pois remove a quarentena apenas do Zig, sem afetar a segurança geral do sistema.

Apple Silicon vs. Intel

Rosetta 2

Se você tem um Mac com Apple Silicon e precisa usar uma versão do Zig compilada para Intel (x86_64), o Rosetta 2 traduz automaticamente. Para instalar o Rosetta 2 (se ainda não estiver instalado):

softwareupdate --install-rosetta --agree-to-license

No entanto, recomendamos sempre usar a versão nativa para aarch64 no Apple Silicon, pois oferece melhor desempenho.

Cross-Compilation no macOS

Uma das grandes vantagens do Zig é a cross-compilation integrada. No seu Mac, você pode compilar para qualquer plataforma:

# Compilar para Linux x86_64
zig build-exe --target=x86_64-linux-gnu hello.zig

# Compilar para Windows
zig build-exe --target=x86_64-windows-gnu hello.zig

# Compilar para Linux ARM (Raspberry Pi)
zig build-exe --target=aarch64-linux-gnu hello.zig

Exemplo completo de cross-compilation:

const std = @import("std");
const builtin = @import("builtin");

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();

    try stdout.print("Sistema: {s}\n", .{@tagName(builtin.os.tag)});
    try stdout.print("Arquitetura: {s}\n", .{@tagName(builtin.cpu.arch)});
    try stdout.print("ABI: {s}\n", .{@tagName(builtin.abi)});
}

Configurando o Terminal no macOS

iTerm2 + Zsh

A maioria dos desenvolvedores no macOS usa iTerm2 com Zsh. Para uma experiência otimizada com Zig:

Instale o iTerm2: brew install --cask iterm2
Adicione o Zig ao PATH no ~/.zshrc (se instalou manualmente)
Considere adicionar um alias útil:

# Adicionar ao ~/.zshrc
alias zb='zig build'
alias zr='zig run'
alias zt='zig test'

Xcode Command Line Tools

Embora o Zig não dependa do Xcode, algumas bibliotecas do macOS podem precisar dos headers do SDK. Instale as Command Line Tools:

xcode-select --install

O Zig detecta automaticamente o SDK do macOS para linkar com bibliotecas do sistema. Se precisar especificar manualmente:

# Verificar onde está o SDK
xcrun --show-sdk-path

Instalando o ZLS no macOS

O ZLS (Zig Language Server) pode ser instalado via Homebrew:

brew install zls

Ou via download manual, seguindo os mesmos passos do Zig. Depois de instalar, configure seu editor:

Problemas Comuns no macOS

“No such file or directory” ao compilar

Verifique se o Xcode Command Line Tools está instalado:

xcode-select -p

Se não estiver, instale com xcode-select --install.

Erro “unable to find macOS SDK”

O Zig precisa encontrar o SDK do macOS para compilar programas que usam bibliotecas do sistema. Isso geralmente é resolvido instalando o Xcode ou as Command Line Tools.

Performance lenta na primeira compilação

A primeira compilação pode ser mais lenta enquanto o Zig preenche seu cache. Compilações subsequentes serão significativamente mais rápidas graças ao cache incremental.

Para mais soluções, visite nossa página de erros comuns.

Próximos Passos

Com o Zig instalado no macOS:

Configure seu editor — VS Code ou Neovim
Crie seu primeiro projeto — Primeiro projeto Zig
Aprenda a linguagem — Introdução ao Zig
Gerencie versões — Gerenciar versões do Zig
Veja exemplos — Receitas

Se você também usa Docker para desenvolvimento, confira nosso guia de Zig com Docker.