Mojo 1.0 Mac Can't Find GPU? 2026 Metal Toolchain Troubleshooting

Mojo runs, but the GPU probe fails with a Metal error.

Fastest fix: do not reject an M1 or M2 Mac first. Check macOS, the Xcode developer path, and the separately installed Metal Toolchain. If a minimal GPU program sees the device but MAX serve still fails, stop reinstalling Mojo and inspect the model, kernel coverage, package split, and available unified memory.

This guide is for:

• Mac developers who can run mojo but get an Apple GPU or Metal error from a GPU example.
• AI engineers evaluating Apple Silicon M1/M2 for MAX serving and unsure whether the problem is chip support or model support.
• Platform owners who need a reproducible Apple Silicon environment, locally or through a remote Mac.

Last updated August 21, 2026. Requirements and package behavior were checked against the Mojo system requirements, MAX package documentation, the MAX 26.5 release notes, and the MAX changelog.

Start with the failure layer

Treat these as three separate conclusions:

1. The Mojo command is installed and runnable.
2. Mojo can call the Apple GPU through Metal.
3. MAX can compile and serve the selected model.

A successful result at one layer does not prove the next layer. This distinction prevents the most expensive troubleshooting mistake: rebuilding a working Mojo environment because one model graph failed later.

Keep the complete terminal output. Do not copy only the final error line. A missing executable, an incorrect developer directory, and an unsupported model can produce similar-looking failures after several layers of logging.

The official Mojo GPU introduction is useful as a controlled test. Use a small example first. Do not begin with your production model because a large graph makes the failure boundary harder to identify.

System and chip requirements

Apple Silicon M1/M2: supported hardware, not a guaranteed model target

Mojo 1.0 officially supports macOS 15 or later, Apple Silicon M1 through M5, and Xcode or Command Line Tools 16 or later. These requirements place Apple Silicon M1/M2 inside the supported hardware range; a missing GPU does not by itself prove that either chip has been dropped. Verify the current requirements in the official Mojo requirements before changing your environment.

Run these checks:

sw_vers
uname -m
system_profiler SPHardwareDataType
xcode-select --print-path
xcrun --find metal
xcrun metal --version

You are checking different facts:

• sw_vers confirms the macOS version.
• uname -m helps confirm that the shell is running on Apple Silicon rather than under an unexpected translation layer.
• system_profiler SPHardwareDataType identifies the actual chip.
• xcode-select --print-path shows which developer directory the system is using.
• xcrun --find metal tests whether the selected developer tools expose the Metal compiler.
• xcrun metal --version provides a concrete tool version to retain in a bug report.

If the Mac is not on macOS 15 or later, or the developer tools are below the documented Xcode 16 boundary, stop the Mojo-level investigation. Upgrade the supported layer, switch to a compliant environment, or test on a remote Apple Silicon Mac. Continuing to alter Python packages cannot repair a missing system prerequisite.

Important: macOS includes the Metal framework used by applications. The additional Metal Toolchain required for development and compilation is a separate component. “Metal works in a graphics application” is not proof that the compiler toolchain is installed.

Multiple Xcode installations make this failure common. A system update can leave xcode-select pointing at an old directory. A deleted Xcode application can leave a path that looks valid but no longer contains the expected tools. The Apple Command Line Tools configuration guide explains how the active developer directory is selected.

Metal Toolchain errors

When downloading the toolchain is the right move

Use the official download command when the documented requirements are satisfied but xcrun --find metal fails, the Metal compiler cannot be located, or a Mojo GPU compilation step reports that the required Metal tools are unavailable:

xcodebuild -downloadComponent MetalToolchain

A download message is not a successful validation. Check the command's exit status, then run the discovery commands again:

echo $?
xcrun --find metal
xcrun metal --version

A zero exit status only tells you that the preceding command completed successfully. It does not prove that Mojo is using the intended Xcode path. The second test should resolve a real metal executable, and the third should return a version.

After that, rerun the minimal GPU program. This is the decisive test. If the toolchain is visible but the smallest GPU example still fails, save both the tool discovery output and the Mojo error. They point to different layers.

macOS or Xcode updates

A system or Xcode update can change the active developer directory or invalidate a previously downloaded tool component. Do not automatically reinstall the whole Mojo stack after an operating system upgrade. Repeat the sequence:

1. Confirm the macOS version.
2. Confirm the chip.
3. Print the active developer directory.
4. Locate the Metal compiler.
5. Check the Metal compiler version.
6. Run the minimal GPU program.

If step 3 points to an old or removed Xcode directory, select the intended developer directory with the Apple-supported xcode-select workflow. For example, after confirming the correct Xcode installation, the command typically takes this form:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Use the actual path on your Mac. Do not paste this path blindly if your Xcode installation is elsewhere. If you use only Command Line Tools, confirm that the selected path matches that setup rather than switching to an absent application bundle.

The distinction matters because a working mojo executable can coexist with a broken system compiler path. Mojo is not necessarily the component that changed.

Package and environment alignment

uv, pixi, and old modular environments

Once the system and Metal checks pass, inspect where every relevant executable and package comes from:

which mojo
mojo --version
which python
python --version
python -m pip show max

If your project uses uv or pixi, run the equivalent checks inside that project environment. The goal is not to choose one tool as universally superior. The goal is to prove that mojo, Python, MAX, and the shell environment belong to the same intended installation.

Common causes of package drift include:

• A global mojo is ahead of, or behind, the project environment.
• A shell resolves an old modular installation before the active virtual environment.
• Stable and nightly packages are mixed.
• Python points into one environment while MAX serve resolves another.
• A project was upgraded without recreating its lockfile or environment.

MAX 26.5 changed the package layout by separating capabilities such as serving and benchmarking. Check the MAX package documentation and select only the component your task needs:

• max[serve] for model serving workflows.
• max[benchmark] for benchmark tooling.
• max[all] when the project genuinely needs the full set.

A missing serving component can look like a runtime or Metal failure if the command starts only far enough to report an unavailable module. Conversely, installing every optional component can make environment diagnosis less clear.

Clean only the environment that is demonstrably inconsistent. Keep a copy of the version output and lockfile first. Do not delete unrelated projects merely because one MAX command fails.

GPU detection versus MAX serving

A working probe does not validate every model

Suppose the minimal GPU program succeeds. That proves the Metal path is usable for that program. It does not prove that every MAX model can compile on the Mac.

MAX on Apple Silicon supports a subset of the models available on NVIDIA or AMD platforms. The official MAX model support page is the authority for the current list. The documented examples include model families such as Llama, Gemma, Nemotron, and FLUX.2, but the exact supported architectures and features can change. Check the current matrix instead of treating a family name as a guarantee for every checkpoint or operation.

At this stage, inspect:

• The exact model architecture, not only its marketing family.
• Whether the required operators and Apple Silicon kernels are covered.
• Whether the chosen MAX package includes serving support.
• The full compiler error, including the first unsupported operation.
• Available unified memory and current memory pressure.
• Whether another process is occupying memory or keeping a previous server alive.

A model compilation error after successful GPU detection is not evidence that an M1 or M2 cannot run Mojo GPU code. It usually changes the decision from “repair Metal” to “validate this model target.”

Do not use a successful Metal probe as a blanket compatibility certificate. It validates the device path. MAX still has to lower the selected model graph to supported Apple Silicon kernels within the available unified memory.

The three-way decision

Use this rule after the probe:

• Probe fails: repair macOS, Xcode selection, Command Line Tools, or Metal Toolchain.
• Probe succeeds and a known-supported model serves: keep the local environment and record the working versions.
• Probe succeeds but the target model fails: verify model support, MAX package selection, memory headroom, and kernel coverage before considering a chip change.

This is also where the phrase “MAX inference on Mac” needs precision. The question is not whether inference exists in the abstract. The question is whether your exact model, operators, quantization path, and serving package are supported on your exact Apple Silicon environment.

A reproducible troubleshooting run

Follow this order so each result narrows the search:

1. Capture the baseline. Save mojo --version, which mojo, Python version, package output, macOS version, chip information, and the full failing command.
2. Confirm the supported platform. Compare macOS, Apple Silicon generation, and Xcode or Command Line Tools against the current Mojo requirements.
3. Check the active developer path. Run xcode-select --print-path, then verify that the selected directory exists and is the one your team expects.
4. Locate Metal. Run xcrun --find metal and xcrun metal --version. If the compiler is missing, download the Metal Toolchain with the official xcodebuild command.
5. Repeat the minimal GPU test. Use the documented Mojo GPU example or your smallest internal probe. Record whether device discovery succeeds.
6. Resolve package identity. Confirm that the mojo, Python, MAX, uv, or pixi paths belong to one environment rather than a mixture of global and project installations.
7. Install the required MAX component. Use max[serve] for serving, max[benchmark] for benchmark work, or max[all] only when the project requires both and more.
8. Test the target model separately. Check the official model support page, then run the smallest serving command that reproduces the compilation error.
9. Inspect memory and architecture. If Metal works, investigate model graph support, Apple Silicon kernel coverage, and current unified-memory availability.
10. Choose the next environment. Repair the local Mac, change to a better-supported model, or reproduce on a remote Apple Silicon Mac with the same diagnostic bundle.

This sequence avoids a false repair. If step 5 passes, repeating steps 1 through 4 cannot make an unsupported model architecture compatible.

Local repair or remote Mac

The local Mac is usually the better choice when you need physical peripherals, interactive debugging, or a long-running workload with a stable configuration. It also avoids network transfer and remote-session variables.

A remote Apple Silicon environment becomes more attractive when:

• The local Mac has insufficient unified memory for the target model.
• Another developer or process frequently occupies the GPU and memory.
• Your team needs the same macOS, Xcode, and package state for repeated tests.
• You need to reproduce a failure without changing a developer's workstation.
• The project is temporary and buying another Mac would leave unused hardware afterward.

Before moving, package the evidence rather than saying only “GPU not found.” Include:

macOS version:
Chip:
mojo path and version:
Python path and version:
MAX package and version:
xcode-select --print-path:
xcrun --find metal:
xcrun metal --version:
Minimal GPU probe result:
Target model:
Full first compiler error:

For team workflows, the MacHTML console can serve as the operational entry point for a remote test environment. Keep the same diagnostic sequence after connection. A remote Mac is useful only if it produces a comparable, inspectable environment rather than becoming a black box.

If you need help identifying the correct setup, the MacHTML help center is the appropriate place to document the macOS, Xcode, chip, and package constraints before requesting a machine.

What to do with M1 and M2 results

Do not make the purchase or migration decision from the phrase “GPU not found” alone.

For Apple Silicon M1/M2:

• If system requirements fail, upgrade or change environments first.
• If Metal discovery fails, repair the developer path and toolchain.
• If the minimal GPU program succeeds, the chip is not automatically disqualified.
• If only one MAX model fails, investigate model support and memory before replacing hardware.
• If several supported models fail after a clean toolchain check, preserve logs and test an isolated environment.
• If the workload repeatedly exceeds local memory or requires team-wide reproducibility, move the same test to a stronger remote Apple Silicon environment.

The August 18, 2026 ModCon announcement also confirmed that the Mojo compiler and toolchain had been announced as fully open source. That announcement does not turn every planned capability into a generally available Mac feature, and an event title or demonstration should not be treated as proof that a specific robotics or serving workflow is already supported. For installation and compatibility decisions, use the current Mojo requirements, MAX package documentation, release notes, and model matrix.

Current setup versus a rented Mac environment

A damaged local setup has three recurring disadvantages: you may lose time to stale Xcode paths, local unified memory can constrain model compilation, and teammates cannot easily reproduce the exact state of your workstation. A permanent second Mac solves some of those problems but adds purchase cost, maintenance, storage, updates, and idle hardware.

Renting a Mac through MacHTML is the more practical route when your need is temporary inference testing, a larger-memory validation run, or a controlled Apple Silicon reproduction environment. It does not replace a local Mac for workloads that require physical USB devices, uninterrupted long-term ownership, or predictable high-volume use. But after your minimal GPU probe is complete, a remote environment gives you a clean comparison: same logs, a different chip or memory tier, and a clear answer about whether the failure belongs to Metal or to the model.

If the evidence points to a broken local environment, rebuild only that environment and keep your captured outputs. If memory, device contention, or team reproducibility is the real constraint, submit the required chip generation, memory target, macOS/Xcode boundary, and usage period through the MacHTML service options. Then rerun the same probe and model command instead of starting a new, unmeasurable experiment.