Skip to main content
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

SymptomFix
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 errorEnsure you are on an Apple Silicon Mac, not a CI runner