Installing Zig Programming Language in a Docker Container

If you’re exploring Zig — the modern systems programming language that aims to replace C — running it inside a Docker container is a clean and isolated way to get started. In this post, we’ll go step-by-step through how to set up a Docker container with Zig installed and ready for use, and how to edit your Zig code directly from Visual Studio Code.

🧩 What You’ll Need

• Docker installed on your machine (Windows, macOS, or Linux)
• Visual Studio Code installed
• Basic familiarity with Docker commands

🛠 Step 1: Create a Dockerfile

Let’s start by creating a file named Dockerfile in an empty folder. This file will define everything your Zig container needs.

FROM debian:bookworm-slim

# Install dependencies
RUN apt-get update && \
    apt-get install -y curl xz-utils build-essential && \
    rm -rf /var/lib/apt/lists/*

# Set Zig version (you can change this)
ENV ZIG_VERSION=0.13.0

# Download and extract Zig
RUN curl -L https://ziglang.org/download/${ZIG_VERSION}/zig-linux-x86_64-${ZIG_VERSION}.tar.xz \
    -o /tmp/zig.tar.xz && \
    tar -xf /tmp/zig.tar.xz -C /opt && \
    ln -s /opt/zig-linux-x86_64-${ZIG_VERSION}/zig /usr/local/bin/zig && \
    rm /tmp/zig.tar.xz

# Set working directory
WORKDIR /app

# Default command
CMD ["zig", "version"]

🧱 Step 2: Build the Docker Image

In your terminal, navigate to the directory where your Dockerfile is located, and run:

docker build -t ziglang .

This command builds the image and tags it as ziglang. Docker will download the base Debian image, install the required packages, and then fetch the Zig compiler.

▶️ Step 3: Run Zig in a Container

Once the image is built, you can run it like this:

docker run --rm ziglang

You should see something like:

0.13.0

That means Zig is installed and working inside your container! You can also open an interactive shell to use Zig manually:

docker run -it --rm ziglang bash

Then inside the container, try:

zig version
zig init-exe

🧮 Step 4: Mount Your Local Code

If you have Zig source files on your host machine, you can mount them into the container to build or test them:

docker run -it --rm -v %cd%:/app ziglang bash

(On macOS/Linux, replace %cd% with $(pwd).)

Now you can run:

zig build

and it will compile your project using the Zig compiler inside the container.

💻 Step 5: Edit Zig Source Code in VS Code

You can easily use Visual Studio Code to edit your Zig project while using Docker for compiling and running. Here’s how:

1. Open your project folder:
   In VS Code, go to File → Open Folder and select the folder that contains your Dockerfile and your Zig source files (e.g., main.zig).
2. Install the Zig Language extension:
   In VS Code, open the Extensions panel (Ctrl+Shift+X) and search for "Zig Language" (by “ziglang”). This provides syntax highlighting, code completion, and inline diagnostics.
3. Use VS Code terminal for Docker commands:
   From inside VS Code’s terminal, you can run the same Docker commands:

   docker run -it --rm -v %cd%:/app ziglang bash

   This links your open folder to the container’s /app directory, so any changes you make in VS Code instantly appear inside the running container.
4. Optional: Use VS Code Dev Containers
   If you install the “Dev Containers” extension (by Microsoft), you can open the entire folder inside the Zig container by adding a simple .devcontainer/devcontainer.json file.

This setup gives you the best of both worlds — Zig runs in an isolated, reproducible Docker environment, while you code comfortably in VS Code on your local machine.

🎯 Final Thoughts

Using Docker to install Zig keeps your development environment clean and portable. You can use the same setup across different machines, CI/CD pipelines, or even share it with teammates. And with VS Code integration, you get the full modern IDE experience without installing Zig locally.

That’s it! You now have a lightweight, reproducible Zig environment running in Docker — fully integrated with VS Code for easy editing and development.