Memory Management in Zig: A Deep Dive

Zig takes a radically different approach to memory management compared to most modern languages. There is no garbage collector, no reference counting, and no mandatory ownership system. Instead, Zig gives you full manual control with explicit allocators, while providing powerful tools to prevent leaks and use-after-free bugs. This tutorial will walk you through everything you need to know to master memory in Zig.

What Is Zig's Memory Model?

At its core, Zig's memory model is simple: all allocations are explicit and visible. Every function that needs to allocate memory receives an Allocator parameter. There is no hidden allocation behind function calls, no implicit heap usage in operators, and no magic. This means when you read Zig code, you can see exactly where memory is being acquired and released.

The fundamental building block is the Allocator interface, defined in the standard library. It provides three essential methods:

alloc – allocate a block of memory
free – release a previously allocated block
resize – grow or shrink an existing allocation

Every concrete allocator type implements this interface, and you pass allocators by reference through your call stack. This design creates a clear, auditable trail of all memory operations in your program.

Why Memory Management Matters in Zig

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Understanding memory management in Zig is not optional—it's central to writing any non-trivial program. Here's why it matters so deeply:

No runtime to clean up after you: Zig has no garbage collector. Memory you allocate stays allocated until you explicitly free it. Leaks in long-running programs accumulate indefinitely.
Performance-critical systems: Zig targets domains like embedded systems, game engines, and operating systems where allocation overhead must be minimized and predictable.
Cross-compilation friendly: Zig code may run on bare metal without an OS-provided heap. You must choose allocators appropriate for your target environment.
Composable libraries: By passing allocators explicitly, libraries never impose allocation strategies on their users. The caller always chooses.

Ignoring memory discipline in Zig leads to leaks, fragmentation, and crashes. Mastering it gives you fine-grained control that few languages can match.

The Zig Philosophy: No Hidden Allocations

The Zig standard library enforces a strict rule: functions that allocate memory must accept an Allocator parameter. Functions that do not accept an allocator will never allocate. This is a design constraint, not just a convention. Consider these contrasting examples:

// BAD: Hidden allocation - this is not idiomatic Zig
fn make_greeting(name: []const u8) []u8 {
    // Where does the allocation come from? Unknown!
    // What allocator is used? Unknown!
    // Who frees this? The caller must guess!
}

// GOOD: Explicit allocator - the Zig way
fn make_greeting(allocator: std.mem.Allocator, name: []const u8) ![]u8 {
    const greeting = try std.fmt.allocPrint(allocator, "Hello, {s}!", .{name});
    return greeting;
    // Caller knows: this was allocated with 'allocator', caller must free it
}

This explicitness eliminates entire categories of bugs. You never wonder "who owns this memory?" because the allocator trail answers that question definitively.

Core Memory Concepts

Allocators

An allocator is any value that implements the std.mem.Allocator interface. The interface is a struct of function pointers, typically created via helper functions. You never work with raw malloc/free directly—instead you go through this abstraction, which enables swapping allocation strategies without changing your business logic.

pub const Allocator = struct {
    ptr: *anyopaque,
    vtable: *const VTable,

    pub const VTable = struct {
        alloc: *const fn (ctx: *anyopaque, len: usize, ptr_align: u29, 
            return_address: usize) Error![]u8,
        resize: *const fn (ctx: *anyopaque, buf: []u8, buf_align: u29, 
            new_len: usize, return_address: usize) Error!usize,
        free: *const fn (ctx: *anyopaque, buf: []u8, buf_align: u29, 
            return_address: usize) void,
    };
};

The return_address parameter is used for stack trace debugging—when an allocation fails or leaks, Zig can tell you exactly where in your code the allocation occurred.

Stack vs Heap

Zig distinguishes clearly between stack-allocated and heap-allocated memory. Stack memory uses fixed-size buffers, arrays, and structs declared with var or const inside functions. Heap memory goes through an allocator. The compiler enforces lifetime constraints—you cannot return a pointer to stack memory from a function:

fn brokenFunction() *u32 {
    var x: u32 = 42;
    return &x;  // compile error: address of stack variable returned
}

fn correctFunction(allocator: std.mem.Allocator) !*u32 {
    const ptr = try allocator.create(u32);
    ptr.* = 42;
    return ptr;  // OK: heap memory outlives the function
}

Use stack memory whenever possible for performance and simplicity. Use heap memory when you need dynamically-sized data or when data must outlive the current function.

The Allocator Interface in Practice

Every allocator provides three core operations. Here's how they work with a concrete allocator:

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer std.debug.assert(gpa.deinit() == .ok);
    const allocator = gpa.allocator();

    // 1. alloc: get a block of memory
    const buffer = try allocator.alloc(u8, 1024);
    defer allocator.free(buffer);

    // 2. resize: grow or shrink existing memory
    const expanded = try allocator.realloc(buffer, 2048);
    // Note: 'buffer' is now invalid, use 'expanded'

    // 3. free: release memory (also handled by defer above)
    allocator.free(expanded);
}

The realloc (and resize) method is crucial—it may return the same pointer or a new one, and the old pointer becomes invalid on success. Always use the returned value.

Common Allocators in the Standard Library

std.heap.GeneralPurposeAllocator

This is the workhorse allocator for most applications. It's a safe, general-purpose heap allocator with built-in leak detection and safety checks. It's the recommended default for development and debugging:

pub fn main() !void {
    var gpa_instance = std.heap.GeneralPurposeAllocator(.{}){};
    defer {
        const leaked = gpa_instance.deinit();
        if (leaked == .leak) {
            @import("std").debug.print("MEMORY LEAKS DETECTED!\n", .{});
        }
    }
    const allocator = gpa_instance.allocator();

    // Use allocator throughout your program
    const data = try allocator.alloc(u8, 512);
    defer allocator.free(data);

    // ... rest of your program
}

Key configuration options for GPA:

var gpa = std.heap.GeneralPurposeAllocator(.{
    .enable_memory_limits = true,          // Track total allocated memory
    .verbose_log = true,                   // Print allocation events
    .retain_metadata = true,               // Keep metadata for better error reports
    .never_tidy = false,                   // Set true for embedded/no-os targets
}){};

std.heap.ArenaAllocator

An arena allocator is perfect for short-lived operations with many small allocations. Instead of freeing individual items, you free the entire arena at once. This is dramatically faster and eliminates use-after-free bugs for the arena's lifetime:

fn processBatch(arena: *std.heap.ArenaAllocator, items: []const Item) !void {
    const allocator = arena.allocator();

    // Make hundreds of allocations - all from the arena
    for (items) |item| {
        const processed = try processItem(allocator, item);
        // No need to free 'processed' individually
    }

    // Single call frees everything at once:
    arena.deinit();
}

Arenas excel in request handlers, batch processing, and frame-based workloads like game loops:

fn gameLoop() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();

    while (running) {
        // Reset arena each frame - O(1) cleanup of all frame allocations
        _ = arena.reset(.retain_capacity);
        const allocator = arena.allocator();

        // All frame allocations go here
        const frame_data = try buildFrame(allocator);
        render(frame_data);
        // Everything freed automatically by reset() next iteration
    }
}

std.heap.FixedBufferAllocator

When you know your maximum memory needs ahead of time, a fixed buffer allocator eliminates all heap interaction. It allocates from a pre-allocated static buffer, making it suitable for embedded systems or performance-critical sections:

fn processWithFixedBuffer() !void {
    var buffer: [4096]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&buffer);
    const allocator = fba.allocator();

    // All allocations come from the 4096-byte buffer
    const list = std.ArrayList(u8).init(allocator);
    defer list.deinit();

    try list.appendSlice(&[_]u8{ 1, 2, 3, 4, 5 });
    // If we exceed 4096 bytes total, alloc() returns error.OutOfMemory

    // No heap interaction at all - deterministic and fast
}

std.heap.page_allocator

This allocator directly requests memory from the operating system. It's coarse-grained (allocates whole pages) and should rarely be used directly. It's most commonly used as the backing allocator for arenas:

// Use page_allocator as backing for arena
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
const allocator = arena.allocator();

std.heap.c_allocator

Wraps the system's C malloc/free. Useful when interfacing with C libraries or when you want the exact behavior of the platform's standard malloc:

const allocator = std.heap.c_allocator;
const buf = try allocator.alloc(u8, 256);
defer allocator.free(buf);

std.heap.LoggingAllocator

Wraps any allocator and logs all allocation activity. Invaluable for debugging allocation patterns:

var logging_allocator = std.heap.LoggingAllocator(
    std.heap.LoggingAllocator.Config{
        .log = std.io.getStdErr(),
        .log_standard = true,
    },
    std.heap.page_allocator,
);
const allocator = logging_allocator.allocator();

// Every alloc/free/resize will be logged to stderr
const buf = try allocator.alloc(u8, 100);
// Log shows: ALLOC 100 bytes at 0x...
defer allocator.free(buf);
// Log shows: FREE 100 bytes at 0x...

std.heap.ThreadSafeAllocator

Wraps an allocator with mutex locking for multi-threaded use:

var thread_safe = std.heap.ThreadSafeAllocator{
    .allocator = std.heap.page_allocator,
};
const allocator = thread_safe.allocator();

How to Use Allocators: Practical Patterns

Allocating Single Items

Use create and destroy for individual heap-allocated objects:

const Player = struct {
    name: []const u8,
    score: u32,
};

fn createPlayer(allocator: std.mem.Allocator, name: []const u8) !*Player {
    const player = try allocator.create(Player);
    player.* = Player{
        .name = name,
        .score = 0,
    };
    return player;
}

fn destroyPlayer(allocator: std.mem.Allocator, player: *Player) void {
    allocator.destroy(player);
}

Allocating Arrays

Use alloc for raw arrays of uniform type:

fn allocateBuffer(allocator: std.mem.Allocator, count: usize) ![]u32 {
    const buffer = try allocator.alloc(u32, count);
    // Initialize all elements
    @memset(buffer, 0);
    return buffer;
}

fn freeBuffer(allocator: std.mem.Allocator, buffer: []u32) void {
    allocator.free(buffer);
}

Working with ArrayList

std.ArrayList is Zig's dynamic array. It requires an allocator for initialization and provides automatic growth:

fn buildList(allocator: std.mem.Allocator) !void {
    var list = std.ArrayList(u32).init(allocator);
    defer list.deinit();  // Frees all internal memory

    // Append items - list grows automatically
    try list.append(42);
    try list.append(100);
    try list.append(256);

    // Access as slice
    const slice = list.items;
    std.debug.print("First item: {d}\n", .{slice[0]});

    // Remove items
    _ = list.pop();
}

String Formatting with Allocators

Zig's formatting functions that produce owned strings require an allocator:

fn formatMessage(allocator: std.mem.Allocator, user: []const u8, age: u32) ![]u8 {
    // allocPrint allocates a new string with the formatted content
    const message = try std.fmt.allocPrint(allocator, 
        "User {s} is {d} years old", .{ user, age });
    return message;
    // Caller must free this string
}

fn buildPath(allocator: std.mem.Allocator, dir: []const u8, file: []const u8) ![]u8 {
    return try std.fs.path.join(allocator, &.{ dir, file });
    // Returns newly allocated path string
}

Building a Custom Data Structure

Here's a complete example of a simple linked list that properly manages memory:

const Node = struct {
    value: i32,
    next: ?*Node,
};

const LinkedList = struct {
    head: ?*Node,
    allocator: std.mem.Allocator,

    pub fn init(allocator: std.mem.Allocator) LinkedList {
        return LinkedList{
            .head = null,
            .allocator = allocator,
        };
    }

    pub fn append(self: *LinkedList, value: i32) !void {
        const node = try self.allocator.create(Node);
        node.* = Node{ .value = value, .next = null };

        if (self.head == null) {
            self.head = node;
            return;
        }

        var current = self.head.?;
        while (current.next != null) {
            current = current.next.?;
        }
        current.next = node;
    }

    pub fn deinit(self: *LinkedList) void {
        var current = self.head;
        while (current) |node| {
            const next = node.next;
            self.allocator.destroy(node);
            current = next;
        }
        self.head = null;
    }
};

Using Multiple Allocator Strategies Together

A powerful pattern is composing allocators. For example, use an arena for temporary computations within a larger GPA-managed context:

fn complexOperation(gpa: std.mem.Allocator, input: []const u8) !Result {
    // Create an arena backed by GPA for temporary allocations
    var arena = std.heap.ArenaAllocator.init(gpa);
    defer arena.deinit();  // Frees all temporary allocations at once
    const temp_alloc = arena.allocator();

    // Temporary work in the arena
    const temp_data = try heavyProcessing(temp_alloc, input);
    // No need to free temp_data individually

    // Permanent result allocated with the main GPA
    const result = try buildResult(gpa, temp_data);
    return result;
    // Arena cleanup frees temp_data automatically
}

defer and errdefer: Automatic Cleanup

Zig's defer and errdefer statements are essential tools for memory management. They ensure cleanup code runs when a scope exits, eliminating the need for manual cleanup at every exit point:

fn processFile(allocator: std.mem.Allocator, path: []const u8) !void {
    const file = try std.fs.cwd().openFile(path, .{});
    defer file.close();  // Always close file when we exit

    const buffer = try allocator.alloc(u8, 4096);
    defer allocator.free(buffer);  // Always free buffer

    const content = try file.readAll(buffer);
    // ... process content ...
    // Both defer blocks execute automatically here
}

errdefer runs only when an error occurs, which is perfect for cleanup on failure paths:

fn allocateResources(allocator: std.mem.Allocator) !struct { a: []u8, b: []u8 } {
    const a = try allocator.alloc(u8, 256);
    errdefer allocator.free(a);  // Free 'a' only if we error after this point

    const b = try allocator.alloc(u8, 512);
    // If we reach here, both allocations succeeded
    // errdefer for 'a' won't run on success

    return .{ .a = a, .b = b };
}

Multiple defer statements execute in LIFO order (last declared, first executed):

fn nestedDefers(allocator: std.mem.Allocator) !void {
    const buf1 = try allocator.alloc(u8, 100);
    defer allocator.free(buf1);  // Freed second

    const buf2 = try allocator.alloc(u8, 200);
    defer allocator.free(buf2);  // Freed first

    // ... use both buffers ...
    // buf2 freed first, then buf1
}

Best Practices for Memory Management in Zig

1. Always Pass Allocators Explicitly

Never hide an allocator inside a module or global variable. Every function that allocates must accept an allocator parameter. This keeps allocation visible and gives callers control:

// GOOD: allocator is a parameter
fn loadConfig(allocator: std.mem.Allocator) !Config { ... }

// BAD: hidden global allocator
var global_allocator: std.mem.Allocator = undefined;
fn loadConfig() !Config { ... }  // Uses global_allocator secretly

2. Use defer Immediately After Allocation

Place defer allocator.free(...) directly after the allocation call. This prevents leaks from early returns or errors between allocation and cleanup:

// GOOD: defer right after alloc
const data = try allocator.alloc(u8, 1024);
defer allocator.free(data);
// ... complex logic with many potential early returns ...

// BAD: defer far from allocation
const data = try allocator.alloc(u8, 1024);
// ... 50 lines of code ...
// ... early return here LEAKS memory ...
defer allocator.free(data);  // Too late!

3. Choose the Right Allocator for the Job

Development/debugging: GeneralPurposeAllocator with leak detection enabled
Batch/request processing: ArenaAllocator for bulk freeing
Embedded/fixed memory: FixedBufferAllocator for deterministic behavior
Production servers: GeneralPurposeAllocator or custom allocator tuned for your workload
Interop with C: c_allocator for malloc/free compatibility

4. Test with Leak Detection

Always run tests with GPA leak detection enabled. Zig's test runner supports this:

test "my allocation test" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer std.debug.assert(gpa.deinit() == .ok);
    const allocator = gpa.allocator();

    const data = try allocator.alloc(u8, 100);
    defer allocator.free(data);

    // ... test logic ...
}

5. Document Ownership in Comments

Clearly document who owns allocated memory returned from functions:

/// Returns a newly allocated string.
/// Caller owns the returned memory and must free it with the same allocator.
fn duplicateString(allocator: std.mem.Allocator, s: []const u8) ![]u8 { ... }

/// Returns a slice into the provided buffer.
/// Caller does NOT own the returned slice - it's borrowed from 'buffer'.
fn findPattern(buffer: []const u8, pattern: []const u8) ?[]const u8 { ... }

6. Use Arena Resets for Long-Running Loops

For loops that run indefinitely, reset the arena periodically to prevent unbounded memory growth:

fn eventLoop() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();

    while (true) {
        // Reset each iteration - bounds memory usage
        _ = arena.reset(.retain_capacity);
        const allocator = arena.allocator();

        const event = try receiveEvent(allocator);
        defer allocator.free(event);  // Optional with arena, but explicit is fine

        try processEvent(event);
    }
}

7. Prefer Stack Allocation When Possible

Use fixed arrays and structs on the stack for compile-time-known sizes:

fn processFixedSize() void {
    var buffer: [256]u8 = undefined;  // Stack-allocated, no allocator needed
    // ... fill and use buffer ...
}  // Automatically cleaned up

Common Pitfalls and How to Avoid Them

Pitfall 1: Forgetting to Free Memory

Symptom: Memory usage grows over time. Solution: Always pair allocation with defer free, and use GPA leak detection during testing.

// WRONG: leak
fn leakyFunction(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 1000);
    // ... use data ...
    // Missing: allocator.free(data);
}

// RIGHT: no leak
fn cleanFunction(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 1000);
    defer allocator.free(data);
    // ... use data ...
}

Pitfall 2: Use-After-Free

Symptom: Crashes, corrupted data, or security vulnerabilities. Solution: Keep alloc/free pairs close together, and don't store freed pointers:

// DANGEROUS: use-after-free
fn dangerousFunction(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 100);
    allocator.free(data);
    // BAD: using 'data' after freeing
    data[0] = 42;  // Undefined behavior!
}

// SAFE: proper lifetime management
fn safeFunction(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 100);
    defer allocator.free(data);
    data[0] = 42;  // Safe: still valid
    // 'data' becomes invalid after defer runs
}

Pitfall 3: Mismatched Allocators

Symptom: Heap corruption, crashes. Solution: Always free memory with the exact allocator that allocated it:

// DANGEROUS: freeing with wrong allocator
fn mismatchedFree(gpa: std.mem.Allocator, arena: *std.heap.ArenaAllocator) !void {
    const data = try gpa.alloc(u8, 100);
    // WRONG: freeing GPA memory with arena allocator
    arena.allocator().free(data);  // CORRUPTION!
}

// CORRECT: matching allocator
fn matchedFree(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 100);
    allocator.free(data);  // Same allocator
}

Pitfall 4: Double Free

Symptom: Heap corruption. Solution: Set pointers to undefined or null after freeing, or ensure defer blocks don't overlap:

fn avoidDoubleFree(allocator: std.mem.Allocator) !void {
    const data = try allocator.alloc(u8, 100);
    allocator.free(data);
    // allocator.free(data);  // DOUBLE FREE - never do this

    // Alternative: use defer and let scope handle it
    const data2 = try allocator.alloc(u8, 100);
    defer allocator.free(data2);
    // defer ensures exactly one free
}

Pitfall 5: Returning Stack Pointers

Symptom: Dangling pointer bugs. Solution: The compiler catches most cases, but be careful with indirect returns:

// CAUGHT by compiler:
fn badReturn() *u32 {
    var x: u32 = 42;
    return &x;  // compile error
}

// NOT caught by compiler - still dangerous:
fn subtleBadReturn() []u8 {
    var buffer: [100]u8 = undefined;
    return &buffer;  // Returns pointer to stack memory - dangling!
}

// CORRECT: use heap allocation
fn goodReturn(allocator: std.mem.Allocator) ![]u8 {
    const buffer = try allocator.alloc(u8, 100);
    return buffer;  // Heap memory, caller must free
}

Conclusion

Memory management in Zig represents a deliberate design choice: make allocations visible, give the programmer complete control, and provide powerful tools to prevent errors. The allocator interface creates a clean separation between what needs memory and how that memory is obtained. Combined with defer, errdefer, arena allocators, and GPA leak detection, Zig gives you industrial-strength memory safety without the runtime overhead of garbage collection or the complexity of borrow checking.

The key takeaways are: always pass allocators explicitly, always pair allocation with defer-based cleanup, choose allocator strategies based on your use case (GPA for general use, arenas for batch operations, fixed buffers for embedded), and test relentlessly with leak detection enabled. Master these patterns, and you'll write Zig code that is fast, predictable, and free of memory bugs—code that's ready for the most demanding systems programming challenges.