CUDA.Zig

cuda.zig is a modern, production-grade CUDA library for Zig, featuring zero-link dynamic loading, complete CUDA Driver and Runtime bindings, high-level GPU abstractions, typed tensor operations, NVRTC runtime compilation, and automatic CPU fallback.

Related Zig projects:

• For env.zig (.env parsing), check out env.zig.
• For TUI support, check out tui.zig.
• For ZON file format support, check out zon.zig.
• For spinners/loading/progress bar support, check out loaders.zig.
• For MCP support, check out mcp.zig.
• For args parsing support, check out args.zig.
• For HTTP client/server support, check out httpx.zig.
• For API framework support, check out api.zig.
• For web framework support, check out zix.
• For archive/compression support, check out archive.zig.
• For compression file format support, check out zigx.
• For file downloading support, check out downloader.zig.
• For update checker/auto-updater support, check out updater.zig.
• For numerical computing support, check out num.zig.
• For logging support, check out logly.zig.
• For data validation and serialization support, check out zigantic.
• For build tooling support, check out buildx.zig.
• For CUDA/GPU computing support, check out cuda.zig.
• For Sqlite support, check out sqlite.zig.
• For Simplified Build.zig support, check out build.zig.

# Build for Linux ARM64 from Windows
zig build -Dtarget=aarch64-linux

# Build for Windows from Linux  
zig build -Dtarget=x86_64-windows

Latest Release (v0.0.2)

zig fetch --save https://github.com/muhammad-fiaz/cuda.zig/archive/refs/tags/0.0.2.tar.gz

Use the latest development version from the main branch.

zig fetch --save git+https://github.com/muhammad-fiaz/cuda.zig.git

Add the dependency to your build.zig.zon file.

.dependencies = .{
    .cuda = .{
        .url = "https://github.com/muhammad-fiaz/cuda.zig/archive/refs/tags/0.0.2.tar.gz",
        .hash = "...", // Run `zig fetch --save <url>` to generate the hash.
    },
},

Clone the repository locally.

git clone https://github.com/muhammad-fiaz/cuda.zig.git
cd cuda.zig
zig build

To use a local checkout from another project, add a path dependency to your build.zig.zon:

.dependencies = .{
    .cuda = .{
        .path = "../cuda.zig",
    },
},

After adding the dependency, import the module in your build.zig:

const cuda_dep = b.dependency("cuda", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("cuda", cuda_dep.module("cuda"));

const std = @import("std");
const cuda = @import("cuda");

pub fn main() !void {
    std.debug.print("=== cuda.zig Quick Start ===\n", .{});

    if (!cuda.isAvailable()) {
        std.debug.print("Operating in CPU Fallback mode (no CUDA GPU detected).\n", .{});
    } else {
        const count = try cuda.deviceCount();
        std.debug.print("Found {d} CUDA device(s).\n", .{count});

        const dev = try cuda.Device.init(0);
        std.debug.print("Device 0: {s}\n", .{try dev.name()});
    }

    // Typed device buffer (works on both GPU and CPU fallback)
    var buf = try cuda.DeviceBuffer(f32).alloc(1024);
    defer buf.free();

    const input_data = [_]f32{ 1.0, 2.0, 3.0, 4.0 };
    try buf.copyFromHost(&input_data);

    var output_data: [4]f32 = undefined;
    try buf.copyToHost(&output_data);

    std.debug.print("Output: {any}\n", .{output_data});
}

const std = @import("std");
const cuda = @import("cuda");

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // N-Dimensional Tensor Broadcasting
    var a = try cuda.Tensor(f32).fromSlice(&.{ 1, 2, 3, 4, 5, 6 }, &.{ 2, 3 });
    defer a.deinit();
    var bias = try cuda.Tensor(f32).fromSlice(&.{ 10, 20, 30 }, &.{3});
    defer bias.deinit();

    var c = try a.broadcastAdd(bias);
    defer c.deinit();

    const result = try c.toHost(allocator);
    defer allocator.free(result);

    std.debug.print("Broadcast Output: {any}\n", .{result});
}

The examples/ directory contains 13 runnable examples:

• 01_device_info - Device enumeration, compute capability, and memory specs
• 02_memory_transfer - Host-to-Device and Device-to-Host transfers
• 03_kernel_launch - Driver API kernel launch configuration
• 04_streams_events - Stream synchronization and Event GPU timing
• 05_tensor_ops - High-level N-dimensional Tensor operations
• 06_multi_gpu - Multi-GPU device selection and peer access
• 07_cpu_fallback - Demonstrating automatic CPU fallback execution
• 08_managed_memory - Advanced Unified Memory allocations, prefetching, and advice
• 09_nvrtc_compilation - Dynamic CUDA C++ source compilation to PTX via NVRTC
• 10_memory_pools_pitched - Stream-ordered memory pool allocations and 2D pitched memory
• 11_occupancy_profiler - Kernel occupancy calculations, stream priorities, and profiler markers
• 12_benchmark_matrix_ops - Parallel N-Body compute benchmark comparing Single-Threaded CPU vs CUDA GPU
• 13_ndarray_tensor_ops - Reshape, transpose, broadcast, axis reductions, batched matmul

To run any example:

zig build example-device-info
zig build example-memory-transfer
zig build example-kernel-launch
zig build example-streams-events
zig build example-tensor-ops
zig build example-multi-gpu
zig build example-cpu-fallback
zig build example-managed-memory
zig build example-nvrtc-compilation
zig build example-memory-pools-pitched
zig build example-occupancy-profiler
zig build example-benchmark-matrix-ops
zig build example-ndarray-tensor-ops

Run all unit tests across the entire codebase:

zig build test

MIT License - Copyright (c) 2026 Muhammad Fiaz