# Installing Zig

### Installing Zig

Before we write more Zig code, we need the Zig compiler.

The compiler is the program that reads your `.zig` source files and turns them into programs your computer can run. Zig is distributed as a single toolchain. After installation, the main command you use is:

```bash
zig
```

The official latest Zig release is `0.16.0`, released on April 14, 2026. The official site lists prebuilt downloads for Windows, macOS, Linux, FreeBSD, NetBSD, and OpenBSD.

In this book, when we say “Zig 1.16,” we are really targeting the Zig `0.16` release line, because Zig has not reached a `1.0` stable release yet.

#### The Best Way to Install Zig

The simplest beginner-friendly method is to download Zig directly from the official website.

Go to the Zig download page, choose the `0.16.0` release, then download the file for your operating system and CPU architecture. The official download page lists files such as `zig-x86_64-linux-0.16.0.tar.xz`, `zig-aarch64-macos-0.16.0.tar.xz`, and `zig-x86_64-windows-0.16.0.zip`.

You do not usually need to build Zig from source. For learning, use a prebuilt binary.

#### Check Your Operating System and CPU

You need to choose the right Zig package.

Most modern desktop computers are one of these:

| System | Common choice |
|---|---|
| Windows on Intel or AMD | `x86_64-windows` |
| macOS on Apple Silicon | `aarch64-macos` |
| macOS on Intel | `x86_64-macos` |
| Linux on Intel or AMD | `x86_64-linux` |
| Linux on ARM | `aarch64-linux` |

Apple Silicon means M1, M2, M3, M4, or later Apple chips.

Intel or AMD desktop and laptop CPUs are usually `x86_64`.

ARM machines are usually `aarch64`.

If you choose the wrong package, the `zig` command may not run.

#### Installing on Windows

Download the Windows `.zip` file from the official Zig download page.

For a normal modern Windows computer, this is usually:

```text
zig-x86_64-windows-0.16.0.zip
```

Extract the zip file somewhere simple, for example:

```text
C:\zig
```

Inside that folder, you should see `zig.exe`.

Now open PowerShell and run:

```powershell
C:\zig\zig.exe version
```

You should see:

```text
0.16.0
```

That proves Zig works.

To make `zig` available everywhere, add `C:\zig` to your `PATH`.

On Windows, `PATH` is a list of folders where the terminal looks for commands. If `C:\zig` is in `PATH`, you can type:

```powershell
zig version
```

instead of:

```powershell
C:\zig\zig.exe version
```

After changing `PATH`, close and reopen PowerShell.

#### Installing on macOS

Download the correct macOS `.tar.xz` file.

For Apple Silicon Macs, use:

```text
zig-aarch64-macos-0.16.0.tar.xz
```

For Intel Macs, use:

```text
zig-x86_64-macos-0.16.0.tar.xz
```

Extract it. You can place the extracted folder somewhere like:

```text
/opt/zig
```

or inside your home directory:

```text
~/tools/zig
```

Then add the folder containing the `zig` executable to your shell path.

If you use `zsh`, which is the default shell on modern macOS, open `~/.zshrc` and add a line like this:

```bash
export PATH="$HOME/tools/zig:$PATH"
```

Then reload your shell configuration:

```bash
source ~/.zshrc
```

Now check:

```bash
zig version
```

Expected output:

```text
0.16.0
```

#### Installing on Linux

Download the correct Linux `.tar.xz` file.

For most Intel or AMD Linux machines, use:

```text
zig-x86_64-linux-0.16.0.tar.xz
```

For ARM Linux machines, use:

```text
zig-aarch64-linux-0.16.0.tar.xz
```

Extract the archive:

```bash
tar -xf zig-x86_64-linux-0.16.0.tar.xz
```

Move it somewhere stable:

```bash
mkdir -p "$HOME/tools"
mv zig-x86_64-linux-0.16.0 "$HOME/tools/zig"
```

Add it to your `PATH`.

If you use Bash, edit `~/.bashrc`:

```bash
export PATH="$HOME/tools/zig:$PATH"
```

Then reload it:

```bash
source ~/.bashrc
```

Now test the install:

```bash
zig version
```

You should see:

```text
0.16.0
```

#### Installing with a Package Manager

You may also install Zig with a package manager.

For example, on some systems you may use tools such as Homebrew, Chocolatey, Scoop, apt, pacman, Nix, or mise.

Package managers are convenient, but they may not always provide the exact version this book uses. The official download page is the safest choice when you want a specific Zig version.

For this book, prefer:

```text
Zig 0.16.0 from the official Zig download page
```

That keeps your compiler version predictable.

#### Checking the Installation

After installation, always run:

```bash
zig version
```

For this book, the expected result is:

```text
0.16.0
```

You can also run:

```bash
zig help
```

This prints the main commands supported by the Zig toolchain.

You will see commands for building, running, testing, formatting, translating C, and more.

Common commands include:

| Command | Meaning |
|---|---|
| `zig build-exe` | Build an executable from a Zig file |
| `zig run` | Build and run a Zig file immediately |
| `zig test` | Run tests in a Zig file |
| `zig fmt` | Format Zig source code |
| `zig build` | Run a project build script |
| `zig cc` | Use Zig as a C compiler |
| `zig c++` | Use Zig as a C++ compiler |

At this stage, you only need three commands:

```bash
zig version
zig run
zig build-exe
```

#### Your First Installation Test

Create a file named:

```text
hello.zig
```

Put this code inside it:

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

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

Now run:

```bash
zig run hello.zig
```

You should see:

```text
Hello from Zig!
```

The `zig run` command compiles the file and runs it in one step.

This is useful while learning because you can quickly test small programs.

#### Building an Executable

Now build the same file as a standalone program:

```bash
zig build-exe hello.zig
```

This creates an executable file.

On Linux and macOS, the output is usually:

```text
hello
```

You can run it with:

```bash
./hello
```

On Windows, the output is usually:

```text
hello.exe
```

You can run it with:

```powershell
.\hello.exe
```

The difference is simple:

| Command | What it does |
|---|---|
| `zig run hello.zig` | Compile and run immediately |
| `zig build-exe hello.zig` | Compile and leave an executable file |

While learning, `zig run` is convenient. For real programs, you often use `zig build` or `zig build-exe`.

#### Common Installation Problems

If your terminal says:

```text
zig: command not found
```

then Zig is not in your `PATH`.

This does not always mean Zig is missing. It usually means your terminal does not know where to find it.

Check where you extracted Zig. Then make sure that folder is listed in your `PATH`.

If Windows says:

```text
'zig' is not recognized as an internal or external command
```

the cause is the same: Windows cannot find `zig.exe`.

Add the Zig folder to `PATH`, then open a new terminal.

If `zig version` prints a different version, you may have another Zig installation earlier in your `PATH`.

You can check which `zig` is being used.

On macOS or Linux:

```bash
which zig
```

On Windows PowerShell:

```powershell
Get-Command zig
```

This shows the location of the Zig executable your terminal is using.

#### What You Installed

After installation, you have more than a compiler.

You have the Zig toolchain.

That includes:

| Toolchain part | Purpose |
|---|---|
| Zig compiler | Compiles Zig source code |
| Build system | Builds projects using `build.zig` |
| Formatter | Formats code with `zig fmt` |
| Test runner | Runs tests with `zig test` |
| C compiler mode | Compiles C code with `zig cc` |
| Cross compiler | Builds programs for other targets |

This is one reason Zig is attractive. It gives you one command, `zig`, that handles many jobs normally split across several tools.

Once `zig version` works and `zig run hello.zig` prints text, your setup is ready.