Getting Started

cuda.zig is a production-grade Zig library that wraps the CUDA Runtime and Driver APIs with zero link-time dependencies. All CUDA symbols are resolved at runtime through dynamic loading, so your binary compiles on any machine — even without a GPU or CUDA Toolkit installed.

Prerequisites

Requirement	Version
Zig	0.16.0 or newer
CUDA Toolkit (optional)	12.x or 13.x (13.3 Update 1 recommended)
GPU (optional)	Any NVIDIA GPU with compute capability 5.0+

Without a GPU or CUDA Toolkit, cuda.zig automatically falls back to a transparent CPU backend that implements the same API surface.

Installation

Stable (via zig fetch)

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

Development / Nightly (directly from GitHub)

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

build.zig.zon

After running zig fetch, your build.zig.zon will contain an entry like:

.dependencies = .{
    .cuda = .{
        .url = "https://github.com/muhammad-fiaz/cuda.zig/archive/refs/tags/v0.0.2.tar.gz",
        .hash = "<sha256 printed by zig fetch>",
    },
},

build.zig

Add the module to your executable:

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

Your First Program

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

pub fn main() !void {
    // Initialize CUDA (falls back silently to CPU if no GPU is available)
    try cuda.init();
    defer cuda.deinit();

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

    // Allocate device memory and copy a slice to the GPU
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    const host_data = [_]f32{ 1, 2, 3, 4, 5, 6, 7, 8 };
    var buf = try cuda.DeviceBuffer(f32).init(allocator, host_data.len);
    defer buf.deinit();

    try buf.copyFromHost(&host_data);

    var result: [8]f32 = undefined;
    try buf.copyToHost(&result);
    std.debug.print("Round-trip OK: {any}\n", .{result});
}

Run with:

zig build run

Next Steps

• Installation guide — build options, feature flags, Docker
• Device Management — enumerate GPUs, read properties
• Memory Buffers — device, host-pinned, managed memory, and stream-ordered pools
• Kernel Launch — PTX, dynamic shared memory, argument marshaling
• Tensor Operations — high-level Tensor(T) elementwise, reduction, matmul
• CPU vs GPU Benchmark — see measured GPU speedup on real hardware