How to Install Zig on Ubuntu 26.04 and 24.04

• Use Ubuntu 26.04 or 24.04, a Bash terminal, internet access and an account with sudo access.
• The archive instructions support Intel/AMD 64-bit (x86_64) and ARM64 (aarch64). Check your architecture before downloading.
• You need tar, xz-utils and an HTTPS downloader such as curl or wget. The commands below install and use curl, plus ca-certificates.
• Choose one installation method. Use sudo for system packages and /opt, but run Zig projects as your normal user.
• Keep the entire extracted Zig bundle, including its lib directory. Moving only the executable can break the installation.

Open a terminal with Ctrl+Alt+T on Ubuntu Desktop:

cat /etc/os-release
uname -m
type -a zig

Expect x86_64 on most Intel/AMD computers or aarch64 on ARM64. A missing Zig command is normal on a new installation. If Zig already exists, check zig version and identify its installation method before adding another copy.

Refresh the package list, then install the tools used below:

sudo apt update
sudo apt install curl ca-certificates tar xz-utils

Review APT’s proposed changes. These tools download and unpack the prebuilt compiler; you do not need to build Zig from source.

Keep this and the next steps in the same Bash terminal. This selects the matching archive and records its published SHA-256 checksum:

zig_version=0.17.1
zig_select_arch() {
case "$(uname -m)" in
  x86_64)
    zig_arch=x86_64
    zig_sha=3581863e3cbcfd0fce0efc682ce7e9e93da96668a977791d356a26d2a7e9b17a
    ;;
  aarch64)
    zig_arch=aarch64
    zig_sha=a1546d5646eb184437918d6635ca6b762a0e889eac09cef720ee7a1ed3fe7795
    ;;
  *) printf 'Use the Zig download page for this architecture.\n'; return 1 ;;
esac
}
zig_select_arch &&
zig_file="zig-${zig_arch}-linux-${zig_version}.tar.xz" &&
zig_setup_dir=$(mktemp -d) &&
curl --fail --location --proto '=https' --tlsv1.2 \
  "https://ziglang.org/download/${zig_version}/${zig_file}" \
  --output "$zig_setup_dir/$zig_file"

For x86_64, the URL is https://ziglang.org/download/0.17.1/zig-x86_64-linux-0.17.1.tar.xz. The order is zig-architecture-linux-version. Use the official download page for other architectures. Stop if the download fails.

Check the downloaded bytes against the checksum for your selected architecture:

printf '%s  %s\n' "$zig_sha" "$zig_setup_dir/$zig_file" | sha256sum --check

Expect the archive path followed by OK. If it reports a mismatch, do not extract or run it. Download it again and compare the release details with the official download index. This detects damaged or mismatched downloads; Zig also publishes Minisign signatures for independent signature verification.

This creates a new directory and refuses to reuse an existing /opt/zig. If it already exists, stop and use the update section after identifying the installation:

sudo mkdir /opt/zig &&
sudo tar -xJf "$zig_setup_dir/$zig_file" \
  --strip-components=1 --no-same-owner -C /opt/zig &&
/opt/zig/zig version

Expect 0.17.1. The strip option removes the archive’s outer directory, so the executable is /opt/zig/zig, with its libraries beside it. If extraction fails after the directory was created, do not continue to the symlink step; use the failed-extraction advice below.

Create the command directory if needed and add a symlink. The ln command deliberately avoids -f, so it will refuse to replace an existing file:

sudo install -d /usr/local/bin &&
sudo ln -sT /opt/zig/zig /usr/local/bin/zig &&
hash -r &&
zig version &&
command -v zig

Expect 0.17.1 and /usr/local/bin/zig. This links to a stable location, so replacing /opt/zig later does not require another .bashrc edit. If the path differs, check the PATH troubleshooting section. You can now skip to the project examples; Snap is an alternative.

Check the channel before installing:

snap version
snap info zig

Under channels, inspect latest/beta and its version. If snap is missing, set up snapd on Ubuntu first. Classic confinement allows broader access to your system than a strictly confined Snap; install only if you trust its publisher.

Do not also install the archive unless you deliberately manage separate versions:

sudo snap install zig --classic --beta
hash -r
zig version
type -a zig

Snap installs whichever version its beta channel currently offers, not a permanently pinned 0.17.1. If /snap/bin is missing from PATH after enabling snapd, sign out and back in. Use the official archive when you need the specific version in this guide.

Use a new directory so the starter files cannot overwrite your work:

zig_project_dir=$(mktemp -d "$HOME/zig-project.XXXXXX") &&
cd "$zig_project_dir" &&
zig init

Zig creates a build.zig build script, build.zig.zon package metadata and starter source files under src. Run pwd and keep the path so you can return to the project.

From that project directory, run:

zig build run

This compiles and runs the generated application. The starter prints a welcome message, including the line below; extra guidance may also appear. The first compilation can take longer while Zig prepares its cache.

Still inside the project:

zig build test

A successful run exits without a build failure. This tests the generated starter, not every future program. Keep build.zig, build.zig.zon and src with your project. Zig creates build caches as needed; do not edit those as source files.

This separate exercise needs no build.zig. Create another new directory, then write a small program:

zig_hello_dir=$(mktemp -d "$HOME/zig-hello.XXXXXX") &&
cd "$zig_hello_dir" &&
cat > hello.zig <<'ZIG'
const std = @import("std");

pub fn main() void {
    std.debug.print("Hello from Zig on Ubuntu!\n", .{});
}
ZIG

The command writes hello.zig only inside the new practice directory. std.debug.print sends this demonstration message to standard error, which is normally visible in your terminal. It is useful for a quick check, rather than a model for production standard-output handling.

In the same directory:

zig run hello.zig

Zig compiles the source and immediately runs it. Expect:

To create a reusable binary instead:

zig build-exe hello.zig -femit-bin=hello
./hello

This writes a hello executable into the practice directory. It prints the same message. Run these commands without sudo. Language and standard-library APIs change between Zig releases, so use the 0.17.1 language reference for this compiler.

After verifying the new archive, extract into an unused staging directory:

sudo mkdir /opt/zig-next &&
sudo tar -xJf "$zig_setup_dir/$zig_file" \
  --strip-components=1 --no-same-owner -C /opt/zig-next &&
/opt/zig-next/zig version

If /opt/zig-next already exists, stop and inspect it. Do not extract a new release over an old bundle: files removed by the new release could remain behind. Run /opt/zig-next/zig build test and /opt/zig-next/zig build run from each project before switching.

Close builds using /opt/zig first. This refuses to proceed when a previous backup already exists:

if [ -e /opt/zig-previous ] || [ -L /opt/zig-previous ]; then
  printf 'Inspect /opt/zig-previous before updating.\n'
else
  sudo mv -T /opt/zig /opt/zig-previous &&
  sudo mv -T /opt/zig-next /opt/zig &&
  hash -r &&
  zig version
fi

The symlink remains /usr/local/bin/zig, pointing to /opt/zig/zig. Keep /opt/zig-previous until your projects work. If the second move fails, restore the directory with sudo mv -T /opt/zig-previous /opt/zig while /opt/zig is absent. For a later rollback after a successful switch, first preserve the new directory under an unused name, then restore the old one.

Check which executable your shell selects:

type -a zig
readlink -f /usr/local/bin/zig
/opt/zig/zig version

For the archive route, the link should resolve to /opt/zig/zig. An older APT, Snap or user-directory installation can take priority. Remove or reconfigure it using its own installation method. Run hash -r afterward. If /usr/local/bin is absent from PATH, add export PATH="/usr/local/bin:$PATH" to ~/.bashrc and open a new Bash terminal.

Do not force the replacement before finding out what owns the path:

ls -ld /usr/local/bin/zig
readlink /usr/local/bin/zig

If it already points to /opt/zig/zig, no new link is needed. Otherwise identify the old installation and preserve or remove it deliberately. Do not overwrite a package-managed executable in /usr/bin.

Inspect the bundle and archive:

ls -ld /opt/zig /opt/zig/lib
ls -l /opt/zig/zig
tar -tJf "$zig_setup_dir/$zig_file" | head

Install xz-utils if tar cannot run xz. Re-download after a checksum failure. If this guide created an incomplete /opt/zig, preserve it under an unused name before repeating extraction into a fresh directory. Keep lib beside the executable; link the executable rather than moving it out of the bundle.

Check architecture and compiler version:

uname -m
zig version

Exec format error usually means the archive targets a different architecture or operating system. Use a Linux archive matching your machine. Missing standard-library members or incompatible build scripts often indicate code written for a different Zig version. Match the project’s required compiler and its versioned documentation rather than mixing examples from master and stable releases.

These removal commands apply only to the /opt/zig installation created here. Inspect the paths and close running builds:

ls -ld /opt/zig /usr/local/bin/zig
readlink /usr/local/bin/zig

Continue only when /opt/zig is your Zig bundle and the link points to /opt/zig/zig. Keep any old compiler backup you still need.

This permanently deletes /opt/zig, including anything you have put inside it. Keep project source in your home directory, outside this installation folder:

if [ "$(readlink /usr/local/bin/zig)" = /opt/zig/zig ]; then
  sudo rm /usr/local/bin/zig &&
  sudo rm -r -- /opt/zig &&
  hash -r
else
  printf 'Link differs; inspect the installation before removing it.\n'
fi

This does not remove your home-directory projects or any separately named backups such as /opt/zig-previous. For a Snap installation, use sudo snap remove zig instead. After removal, type -a zig can reveal another installed copy.