CUDA.Zig

A production-ready, high-performance CUDA Runtime and Driver API library for Zig.

Documentation | API Reference | Quick Start | Contributing

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.

Tip

If you build with cuda.zig, make sure to give it a star. ⭐

Note

Production Readiness: cuda.zig is zero-dependency at link-time. It probes system libraries dynamically (nvcuda.dll / cudart64_*.dll / libcuda.so / libcudart.so) and gracefully switches to a CPU fallback implementation when CUDA is unavailable, ensuring downstream applications never hard-crash.

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.

---

Features (click to expand)

Feature	Description
Dynamic Library Loader	Runtime resolution of CUDA Driver (nvcuda.dll / libcuda.so), Runtime (cudart), and NVRTC with zero link-time dependencies.
Toolkit Version Compatibility	Native support for CUDA 12.0 through 13.3 Update 1 with automatic ABI detection.
Transparent CPU Fallback	Automatic fallback to pure Zig CPU implementations for memory allocations and tensor operations when no CUDA GPU is detected.
Device Selection & Properties	Enumeration of all visible CUDA devices, compute capability queries, memory size reporting, and threadlocal device context management.
Typed Memory Buffers	High-level DeviceBuffer(T), PinnedBuffer(T) (page-locked DMA host memory), and UnifiedBuffer(T) (managed memory with prefetch/advise).
Synchronous & Asynchronous Copies	Typed H2D, D2H, and D2D memory transfers (sync and stream-ordered async).
Streams & Events	High-level wrappers for Stream and Event with elapsed time calculation and stream synchronization.
Kernel Launch & Modules	Arbitrary POD argument marshaling for kernel launches, module loading (PTX / cubin), and Function lookup.
NVRTC Compilation	Runtime compilation of CUDA C++ source strings to PTX assembly.
Multi-GPU & Peer Access	canAccessPeer, enablePeerAccess, disablePeerAccess, and cross-device transfers.
Tensor Abstraction	Generic Tensor(T) struct supporting shape manipulation, elementwise ops (add, sub, mul, div, relu), reductions (sum, mean), and matrix multiplication.
CudaAllocator	std.mem.Allocator vtable implementation backed by GPU global device memory.

---

Prerequisites and Supported Platforms (click to expand)

Prerequisites

Before using cuda.zig, ensure you have the following:

Requirement	Version	Notes
Zig	0.16.0+	Download from ziglang.org
Operating System	Windows 10+, Linux, macOS	Cross-platform GPU computing
CUDA Driver (Optional)	12.0 - 13.3	Optional runtime dependency; falls back to CPU if absent

---

Supported Platforms

cuda.zig is validated on these architectures:

Platform	x86_64 (64-bit)	aarch64 (ARM64)
Linux	Yes	Yes
Windows	Yes	Yes
macOS	Yes (CPU fallback mode)	Yes (CPU fallback mode)

Cross-Compilation

Zig makes cross-compilation easy. Build for any target from any host:

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

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

---

Installation

Method 1: Zig Fetch (Recommended)

Latest Stable Release (v0.0.1)

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

Method 2: Zig Fetch (Development / Nightly)

Use the latest development version from the main branch.

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

Method 3: Manual build.zig.zon Configuration

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

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

Method 4: Local Source Checkout

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",
    },
},

Wire into build.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"));

Quick Start

Basic Device Query & Memory Allocation

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});
}

Tensor Operations

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

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

    const a_data = [_]f32{ 1.0, 2.0, 3.0, 4.0 };
    const b_data = [_]f32{ 5.0, 6.0, 7.0, 8.0 };

    var a = try cuda.Tensor(f32).fromSlice(&a_data, &.{ 2, 2 });
    defer a.deinit();

    var b = try cuda.Tensor(f32).fromSlice(&b_data, &.{ 2, 2 });
    defer b.deinit();

    var c = try a.matmul(b);
    defer c.deinit();

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

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

Examples

The examples/ directory contains 9 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

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

Validation & Testing

Run all unit tests across the entire codebase:

zig build test

License

MIT License - Copyright (c) 2026 Muhammad Fiaz