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