> ## Documentation Index
> Fetch the complete documentation index at: https://klyne-research.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  Python distributions above 3.13 are not supported.
</Warning>

```bash theme={null}
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:

```bash theme={null}
xcode-select --install
```

Verify the Metal compiler is reachable:

```bash theme={null}
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

```bash theme={null}
python -m pip install -U pip
pip install enigma
```

### From source

```bash theme={null}
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:

```python theme={null}
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](/getting-started/compile-only-workflow) instead.

```python theme={null}
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 |