Installation

Install Enigma and verify the Metal toolchain before running your first kernel.

Enigma has two hard dependencies: a Python environment and Apple Metal build tools. Runtime execution requires an Apple Metal device (any Apple Silicon Mac).

Prerequisites

Python

Enigma requires Python 3.11 through Python 3.13.

Python distributions above 3.13 are not supported.

python3 --version
# Python 3.11.x, 3.12.x, or 3.13.x

Xcode Command Line Tools

Enigma invokes xcrun metal and xcrun metallib directly during compilation. Install Xcode CLT if you have not already:

xcode-select --install

Verify the Metal compiler is reachable:

xcrun -sdk macosx metal -v

You should see a version line like Apple metal version 32023.155 (metalfe-32023.155). If this command fails, reinstall Xcode CLT before proceeding.

Install Enigma

python -m pip install -U pip
pip install enigma

From source

git clone https://github.com/enigma-ml/enigma-dsl
cd enigma-dsl
pip install -e ".[dev]"

Verify the installation

Run this snippet. It traces a kernel, invokes the Metal compiler, and prints the compiled kernel name:

import enigma

@enigma.kernel
def sanity(A: enigma.f32, B: enigma.f32, C: enigma.f32):
    tid = enigma.thread_position_in_grid
    C[tid] = A[tid] + B[tid]

compiled = enigma.compile(sanity)
print(compiled.kernel_name)     # enigma_kernel_sanity
print(compiled.metallib_path)   # /tmp/.../sanity.metallib

If this runs without errors, your toolchain is ready.

Runtime execution

Runtime execution additionally requires an Apple Metal device. If you are working in a headless CI environment, use the compile-only workflow instead.

import enigma
import numpy as np

rt = enigma.MetalRuntime()
caps = rt.device_capabilities()
print(caps.gpu_family)          # e.g. "apple9"

Common setup issues

Symptom	Fix
xcrun: error: unable to find utility "metal"	Reinstall Xcode CLT: xcode-select --install
ModuleNotFoundError: No module named 'enigma'	Verify active virtualenv, re-run pip install enigma
MetalRuntime fails with device error	Ensure you are on an Apple Silicon Mac, not a CI runner