img2gray-metal

Metal kernels 🤘

Instructions on this page assume that you installed Nix with the Determinate Nix installer.

Setup Nix

Install Nix Package Manager

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)
nix --verison

Add current user to configure binary cache

echo "trusted-users = $USER" | sudo tee -a /etc/nix/nix.conf && sudo pkill nix-daemon

Install cachix

nix-env -iA cachix -f https://cachix.org/api/v1/install

Setup huggingface cache

cachix use huggingface

Targeted macOS versions

Since new macOS versions get adopted quickly, we only support the latest major macOS version except for the first weeks after a release, when we also support the previous major version.

We currently support macOS 26.0 and later on ARM64 (Apple silicon).

Requirements

To build a Metal kernel, the following requirements must be met:

• Xcode 26.x must be available on the build machine.

• xcode-select -p must point to the Xcode 26 installation, typically /Applications/Xcode.app/Contents/Developer. If this is not the case, you can set the path with: sudo xcode-select -s /path/to/Xcode.app/Contents/Developer

• The Metal Toolchain must be installed. Starting with macOS 26, this is a separate download from Xcode. You can install it with: xcodebuild -downloadComponent MetalToolchain

• The Nix sandbox should be set to relaxed, because the Nix derivation that builds the kernel must have access to Xcode and the Metal Toolchain. You can verify this by checking that /etc/nix/nix.custom.conf contains the line:

  sandbox = relaxed
  

  If you had to add the line, make sure to restart the Nix daemon:

  sudo launchctl kickstart -k system/systems.determinate.nix-daemon
  

You can check these requirements as follows. First, you can check the Xcode version as follows:

$ xcodebuild -version
Xcode 26.1
Build version 17B55

The reported version must be 26.0 or newer. Then you can validate that the Metal Toolchain is installed with:

$ xcodebuild -showComponent metalToolchain
Asset Path: /System/Library/AssetsV2/com_apple_MobileAsset_MetalToolchain/68d8db6212b48d387d071ff7b905df796658e713.asset/AssetData
Build Version: 17B54
Status: installed
Toolchain Identifier: com.apple.dt.toolchain.Metal.32023
Toolchain Search Path: /private/var/run/com.apple.security.cryptexd/mnt/com.apple.MobileAsset.MetalToolchain-v17.2.54.0.mDxgz0

Activate virtual environment

source .venv/bin/activate

Build quickly. Here --max-jobs specifies the number of build variant that should be built concurrently and --cores the number of CPU cores that should be used per build variant.

nix run .#build-and-copy \
  --max-jobs 8 \
  --cores 8 \
  -L

Fix errors

1. error: experimental Nix feature 'nix-command' is disabled; add '--extra-experimental-features nix-command' to enable it

Add the following line to your Nix configuration file, typically located at ~/.config/nix/nix.conf or /etc/nix/nix.conf

experimental-features = nix-command flakes

warning: ignoring the client-specified setting 'trusted-public-keys', because it is a restricted setting and you are not a trusted user To fix these warnings, you need to add your username to the trusted-users list in your Nix configuration. This grants you permission to specify additional binary caches (substituters) and keys.

You should add the following line to

echo "trusted-users = root $USER" | sudo tee -a /etc/nix/nix.conf

1. error: build.toml seems to be of an older version, update it with:

             nix run github:huggingface/kernel-builder#build2cmake update-build build.toml

PreRequiste:

1. Xcode 26.x Install XCode from App Store
2. xcodebuild failed to load a required plug-in. Ensure your system frameworks are up-to-date by running 'xcodebuild -runFirstLaunch'
3. Install Metal Toolchain

xcodebuild -downloadComponent MetalToolchain