Zig Compiler CLI Reference

Complete reference for all Zig compiler commands, options, and flags.

Commands

Project Management

`zig build`

Build project from build.zig.

zig build [options]

Builds a Zig project using the build script. The build script defines compilation targets and dependencies.

`zig init`

Initialize a Zig package in the current directory.

zig init

Creates a new Zig project with a basic build.zig and source files.

`zig fetch`

Copy a package into global cache and print its hash.

zig fetch <package-url>

Downloads and caches a package, printing its content hash for use in build.zig.zon.

Compilation Commands

`zig build-exe`

Create executable from source or object files.

zig build-exe [options] [files]

Example
With C Files

zig build-exe main.zig
zig build-exe -O ReleaseFast main.zig
zig build-exe -target x86_64-linux main.zig

zig build-exe main.zig helper.c -lc

`zig build-lib`

Create library from source or object files.

zig build-lib [options] [files]

Static Library
Dynamic Library

zig build-lib -static mylib.zig

zig build-lib -dynamic mylib.zig

`zig build-obj`

Create object file from source.

zig build-obj [options] [files]

Produces a .o (or .obj on Windows) object file.

`zig test`

Perform unit testing.

zig test [options] [files]

zig test mytest.zig

`zig test-obj`

Create object file for unit testing.

zig test-obj [options] [files]

Produces a test object file (.o or .obj) that can be linked with other test code.

`zig run`

Create executable and run immediately.

zig run [options] [files] [-- [args]]

Compiles and immediately executes the program. Arguments after -- are passed to the program.

zig run main.zig -- --verbose input.txt

Code Tools

`zig fmt`

Reformat Zig source into canonical form.

zig fmt [files/dirs]

Format Files
Check Only

zig fmt src/
zig fmt main.zig lib.zig

zig fmt --check src/

`zig ast-check`

Look for simple compile errors in any set of files.

zig ast-check [files]

Quickly validates Zig syntax without full semantic analysis.

`zig reduce`

Minimize a bug report.

zig reduce [options] [files]

Automatically minimizes a Zig source file that triggers a compiler bug, producing the smallest possible reproduction case.

`zig translate-c`

Convert C code to Zig code.

zig translate-c [options] [file]

zig translate-c header.h

The generated Zig code may require manual adjustments for idiomatic Zig patterns.

C/C++ Compatibility

Zig can be used as a drop-in replacement for various C/C++ tools:

`zig cc`

Use Zig as a drop-in C compiler.

zig cc [clang-compatible-options]

`zig c++`

Use Zig as a drop-in C++ compiler.

zig c++ [clang-compatible-options]

`zig ar`

Use Zig as a drop-in archiver.

zig ar [options] archive.a obj1.o obj2.o

Other Tools

zig dlltool - Windows DLL tool
zig lib - Windows lib.exe replacement
zig ranlib - Generate archive index
zig objcopy - Copy and translate object files
zig rc - Windows resource compiler

Information Commands

`zig version`

Print version number and exit.

zig version
# Output: 0.16.0

`zig env`

Print lib path, std path, cache directory, and version.

zig env

{
  "zig_exe": "/usr/local/bin/zig",
  "lib_dir": "/usr/local/lib/zig",
  "std_dir": "/usr/local/lib/zig/std",
  "global_cache_dir": "/home/user/.cache/zig",
  "version": "0.16.0"
}

`zig targets`

List available compilation targets.

zig targets

Displays all supported CPU architectures, operating systems, and ABIs.

`zig libc`

Display native libc paths file or validate one.

zig libc [path]

`zig std`

View standard library documentation in a browser.

zig std

`zig zen`

Print Zen of Zig and exit.

zig zen

General Options

Help

-h, --help

Print command-specific usage information.

Color Output

--color [auto|off|on]

Enable or disable colored error messages. Default is auto.

Auto (default)
Force On
Force Off

zig build-exe main.zig --color auto

zig build-exe main.zig --color on

zig build-exe main.zig --color off

Concurrency

-j<N>

Limit concurrent jobs. Default uses all CPU cores.

zig build-exe -j4 main.zig

Build Artifacts

Binary Output

-femit-bin[=path]       # (default) Output machine code
-fno-emit-bin           # Do not output machine code

Assembly Output

-femit-asm[=path]       # Output .s assembly file
-fno-emit-asm           # (default) Do not output assembly

LLVM IR Output

Requires LLVM extensions (Zig must be built with LLVM support).

-femit-llvm-ir[=path]   # Produce optimized .ll file
-fno-emit-llvm-ir       # (default) Do not produce .ll file

LLVM Bitcode Output

-femit-llvm-bc[=path]   # Produce optimized .bc file
-fno-emit-llvm-bc       # (default) Do not produce .bc file

C Header Output

-femit-h[=path]         # Generate C header file
-fno-emit-h             # (default) Do not generate header

Documentation Output

-femit-docs[=path]      # Create docs/ directory with HTML
-fno-emit-docs          # (default) Do not produce documentation

Import Library (Windows)

-femit-implib[=path]    # (default) Produce import .lib for DLL
-fno-emit-implib        # Do not produce import library

Cache Directories

--cache-dir [path]         # Override local cache directory
--global-cache-dir [path]  # Override global cache directory
--zig-lib-dir [path]       # Override Zig lib directory path

Compilation Name

--name [name]              # Set compilation unit name (not file path)

The name affects the output filename and library names, but is not a file path.

Supported File Types

Extension	Type	Description
`.zig`	Zig source	Zig source code
`.o`	Object	ELF/Mach-O/WebAssembly object
`.obj`	Object	COFF (Windows) object
`.a`	Archive	Static library (ELF/Mach-O/Wasm)
`.lib`	Archive	COFF static library
`.so`	Shared	ELF shared object
`.dll`	Shared	Windows dynamic library
`.dylib`	Shared	macOS dynamic library
`.tbd`	Text	macOS text-based dylib definition
`.s`	Assembly	Target-specific assembly
`.S`	Assembly	Assembly with C preprocessor
`.c`	C source	C source (requires LLVM)
`.cpp`, `.cc`, `.cxx`, `.C`, `.c++`	C++ source	C++ source (requires LLVM)
`.m`	Obj-C	Objective-C (requires LLVM)
`.mm`	Obj-C++	Objective-C++ (requires LLVM)
`.bc`	LLVM	LLVM IR Module (requires LLVM)

Next Steps

Compilation Modes

Learn about Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall modes

Optimization

Understand optimization levels and strategies

Debugging

Debug Zig programs effectively

C Interop

Work with C code and libraries

Get Started

Language Guide

Build System

Standard Library

Compiler

Documentation Index

​Zig Compiler CLI Reference

​Commands

​Project Management

​zig build

​zig init

​zig fetch

​Compilation Commands

​zig build-exe

​zig build-lib

​zig build-obj

​zig test

​zig test-obj

​zig run

​Code Tools

​zig fmt

​zig ast-check

​zig reduce

​zig translate-c

​C/C++ Compatibility

​zig cc

​zig c++

​zig ar

​Other Tools

​Information Commands

​zig version

​zig env

​zig targets

​zig libc

​zig std

​zig zen

​General Options

​Help

​Color Output

​Concurrency

​Build Artifacts

​Binary Output

​Assembly Output

​LLVM IR Output

​LLVM Bitcode Output

​C Header Output

​Documentation Output

​Import Library (Windows)

​Cache Directories

​Compilation Name

​Supported File Types

​Next Steps

Compilation Modes

Optimization

Debugging

C Interop

Build docs developers (and LLMs) love

Zig Compiler CLI Reference

Commands

Project Management

`zig build`

`zig init`

`zig fetch`

Compilation Commands

`zig build-exe`

`zig build-lib`

`zig build-obj`

`zig test`

`zig test-obj`

`zig run`

Code Tools

`zig fmt`

`zig ast-check`

`zig reduce`

`zig translate-c`

C/C++ Compatibility

`zig cc`

`zig c++`

`zig ar`

Other Tools

Information Commands

`zig version`

`zig env`

`zig targets`

`zig libc`

`zig std`

`zig zen`

General Options

Help

Color Output

Concurrency

Build Artifacts

Binary Output

Assembly Output

LLVM IR Output

LLVM Bitcode Output

C Header Output

Documentation Output

Import Library (Windows)

Cache Directories

Compilation Name

Supported File Types

Next Steps