---
title: "Zig no Linux — Resolver Problemas Específicos"
url: "https://ziglang.com.br/troubleshooting/zig-no-linux-resolver-problemas-espec%C3%ADficos/"
markdown_url: "https://ziglang.com.br/troubleshooting/zig-no-linux-resolver-problemas-espec%C3%ADficos.MD"
description: "Guia para resolver problemas de Zig no Linux. Instalação, glibc vs musl, bibliotecas de desenvolvimento, permissões, distros e configuração de ambiente."
date: "2026-02-21"
author: "Zig Brasil"
---

# Zig no Linux — Resolver Problemas Específicos

Guia para resolver problemas de Zig no Linux. Instalação, glibc vs musl, bibliotecas de desenvolvimento, permissões, distros e configuração de ambiente.


# Zig no Linux — Resolver Problemas Específicos

Zig roda nativamente no Linux e é a plataforma principal de desenvolvimento. Mesmo assim, existem problemas específicos que podem ocorrer dependendo da distribuição e configuração.

## Zig Não Encontrado após Instalação

**Sintoma:** `zig: command not found`

```bash
# Verificar se está no PATH
which zig
echo $PATH

# Adicionar ao PATH (bash)
echo 'export PATH=$PATH:/caminho/para/zig' >> ~/.bashrc
source ~/.bashrc

# Ou para zsh
echo 'export PATH=$PATH:/caminho/para/zig' >> ~/.zshrc
source ~/.zshrc

# Verificar se o binário tem permissão de execução
ls -la /caminho/para/zig
chmod +x /caminho/para/zig
```

## Erro: "GLIBC_X.XX not found"

**Causa:** O binário do Zig (ou de programa compilado) requer uma versão de glibc mais nova que a do sistema.

```bash
# Verificar versão do glibc
ldd --version

# Soluções:
# 1. Usar musl em vez de glibc (recomendado)
zig build -Dtarget=x86_64-linux-musl

# 2. Compilar com linkagem estática
# No build.zig:
# exe.linkage = .static;

# 3. Atualizar o sistema (se possível)
sudo apt update && sudo apt upgrade
```

Para distribuição de binários, **musl** é recomendado pois gera binários completamente estáticos que rodam em qualquer distribuição Linux.

## Erro: Faltam Pacotes de Desenvolvimento

**Sintoma:** Headers não encontrados ao usar `@cImport`.

```bash
# Ubuntu/Debian — instalar headers de desenvolvimento
sudo apt install build-essential
sudo apt install libssl-dev      # OpenSSL
sudo apt install libsqlite3-dev  # SQLite
sudo apt install libz-dev        # zlib
sudo apt install pkg-config      # Para encontrar bibliotecas

# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install openssl-devel
sudo dnf install sqlite-devel
sudo dnf install zlib-devel
sudo dnf install pkg-config

# Arch Linux
sudo pacman -S base-devel
sudo pacman -S openssl
sudo pacman -S sqlite
sudo pacman -S pkg-config
```

## Problema: Permissões de Execução

```bash
# Binário compilado não executa
chmod +x ./zig-out/bin/meu-app

# Verificar se o sistema permite execução no diretório
# Partições montadas com 'noexec' bloqueiam execução
mount | grep $(df . --output=source | tail -1)

# Se estiver em /tmp com noexec:
# Mova para outro diretório ou remonte
```

## Problema: libc Linking

```zig
// No build.zig — escolher entre glibc e musl
const target = b.standardTargetOptions(.{});

// Para binário que roda em qualquer Linux:
// zig build -Dtarget=x86_64-linux-musl

// Para usar bibliotecas do sistema que dependem de glibc:
// zig build -Dtarget=x86_64-linux-gnu
exe.linkLibC();
```

### glibc vs musl

| Aspecto | glibc | musl |
|---------|-------|------|
| Compatibilidade | Com bibliotecas do sistema | Binário portável |
| Tamanho | Maior (linkagem dinâmica) | Menor (estático) |
| Performance | Ligeiramente mais rápido | Muito bom |
| Distribuição | Precisa de glibc compatível | Roda em qualquer Linux |
| DNS | Suporte completo | Funcionalidade limitada |

## Problema: Distro Antiga com Kernel Antigo

```bash
# Verificar versão do kernel
uname -r

# Zig requer kernel relativamente recente para algumas features
# Se o kernel é muito antigo:

# Opção 1: Atualizar o kernel
sudo apt install linux-generic-hwe-22.04  # Ubuntu

# Opção 2: Compilar com musl para maior compatibilidade
zig build -Dtarget=x86_64-linux-musl
```

## Problema: perf e Profiling

```bash
# Instalar perf
# Ubuntu/Debian
sudo apt install linux-tools-common linux-tools-$(uname -r)

# Fedora
sudo dnf install perf

# Rodar com perf
perf record ./zig-out/bin/meu-app
perf report

# Se perf diz "access denied":
# Temporário:
sudo sysctl kernel.perf_event_paranoid=-1

# Permanente:
echo 'kernel.perf_event_paranoid=-1' | sudo tee /etc/sysctl.d/99-perf.conf
sudo sysctl -p
```

## Problema: Systemd Service

Para rodar um binário Zig como serviço:

```ini
# /etc/systemd/system/meu-app.service
[Unit]
Description=Meu App Zig
After=network.target

[Service]
Type=simple
ExecStart=/opt/meu-app/meu-app
Restart=on-failure
RestartSec=5
User=meu-app
Group=meu-app
WorkingDirectory=/opt/meu-app

# Limites de memória e CPU (opcional)
MemoryMax=512M
CPUQuota=200%

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now meu-app
sudo systemctl status meu-app
sudo journalctl -u meu-app -f  # Ver logs
```

## Problema: Docker

```dockerfile
# Dockerfile mínimo para app Zig
FROM alpine:latest AS runner
# Alpine usa musl — compile com -Dtarget=x86_64-linux-musl
COPY zig-out/bin/meu-app /usr/local/bin/meu-app
CMD ["meu-app"]

# Ou binário estático com scratch (menor imagem possível)
FROM scratch
COPY zig-out/bin/meu-app /app
ENTRYPOINT ["/app"]
```

```bash
# Compilar para Docker (musl para imagem Alpine/scratch)
zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe

# Build e rodar
docker build -t meu-app .
docker run meu-app
```

## Problema: Valgrind e Sanitizers

```bash
# Instalar Valgrind
sudo apt install valgrind  # Ubuntu/Debian
sudo dnf install valgrind  # Fedora

# Rodar com Valgrind
valgrind --leak-check=full --show-leak-kinds=all ./zig-out/bin/meu-app

# Usar AddressSanitizer do Zig
zig build-exe src/main.zig -fsanitize=address
./main
```

## Veja Também

- [Instalação](/instalacao/) — Instalar Zig no Linux
- [Cross-Compile Falha](/troubleshooting/zig-cross-compile-falha/) — Compilação cruzada
- [Linkar Biblioteca C](/troubleshooting/zig-c-library-link/) — Problemas de linkagem
- [CI Falha](/troubleshooting/zig-ci-falha/) — Zig em pipelines CI
- [FAQ Build System](/faq/faq-build-system/) — Configuração de build