Xcode 26 will not compile Metal shaders because the Metal Toolchain is missing
A build fails on .metal files and Xcode asks you to download the Metal ToolchainShort answer
Since Xcode 26 the Metal Toolchain is an optional component that is not installed with Xcode. Any target with .metal files, including Core Image kernels and some game or camera packages, fails until you install it. Get it in Xcode Settings under Components, or run xcodebuild -downloadComponent metalToolchain.
Fix it fast
1Find out which cause you have
Ask the active Xcode where its metal compiler is. If the command prints a path and the build still fails, skip to the last cause.
xcode-select -p xcrun -f metal2Match what you see, then jump to its fix
- 1
The build fails on the first .metal file and xcrun -f metal finds no toolThe Metal Toolchain component was never installedFix - 2
The download in Settings or Terminal never finishes, or the build machine has no access to Apple's serversThe Mac cannot download it (managed or offline machine, CI image)Fix - 3
Settings shows the toolchain as installed, yet xcodebuild or Xcode still reports the toolchain as unavailableThe toolchain is installed but this Xcode build does not find itFix
- 1
What does the error look like?
A build fails on .metal files and Xcode asks you to download the Metal ToolchainDownloaded Metal Toolchain may appear unavailable in Xcode when building metal projects
Cause 1 of 3
The Metal Toolchain component was never installed
1Check
Open Xcode > Settings > Components and look under Other Components for Metal Toolchain. Apple describes the toolchain as optional: you download it for the platforms your app targets.
xcrun -f metal2Fix
Click Get next to Metal Toolchain in Xcode > Settings > Components. If a dialog appears during a build, click Download. The same install works from Terminal.
xcodebuild -downloadComponent metalToolchain3Verify
The tool path prints, then build again.
xcrun -f metalConfirmed by developer.apple.com
Cause 2 of 3
The Mac cannot download it (managed or offline machine, CI image)
1Check
Decide which machine can reach Apple's servers. The component can be exported to a file on that machine and imported on the other one.
xcodebuild -downloadComponent metalToolchain -exportPath ~/Downloads2Fix
Copy the exported disk image to the machine that cannot download, then import it into the Xcode that machine uses.
xcodebuild -importComponent metalToolchain ~/Downloads/metalToolchain.dmg3Verify
Confirm the compiler is now found by the selected Xcode.
xcrun -f metalConfirmed by developer.apple.com
Cause 3 of 3
The toolchain is installed but this Xcode build does not find it
1Check
Apple's Xcode 26 release notes list fixes for the downloaded toolchain showing as unavailable, for a stale xcrun cache after the download, and for xcodebuild not finding it on the command line. Compare your Xcode version with the latest 26.x.
xcodebuild -version
xcrun -f metal2Fix
Install the newest Xcode 26.x, make sure the command-line tools point at it, and download the component again from Settings.
sudo xcode-select -s /Applications/Xcode.app3Verify
Run the build from the command line and from Xcode.
xcodebuild -version && xcrun -f metalConfirmed by developer.apple.com
How do I stop it coming back?
- On a build server, add the component install (or an import of an exported copy) to the image setup, so every Xcode update is followed by the same step.
- After switching Xcode versions with xcode-select, run xcrun -f metal once to confirm the compiler is found.
- Keep Xcode on the latest 26.x release.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Mobile apps
Cannot change the App Privacy answers in App Store Connect
Publish Your App Privacy Responses?
Only the Account Holder, Admin and App Manager roles can answer the App Privacy questions.
2 causes, each with a fixMobile apps
App record creation fails because you lack permission
You cannot add a new app in App Store Connect as a Developer or limited user
Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.
3 causes, each with a fixMobile apps
You cannot find the button to pull your app back from review
No 'remove this version from review' message appears on the version page
There is no button called Reject Binary.
3 causes, each with a fixMobile apps
Your Apple Account cannot sign in to App Store Connect
Sign-in to App Store Connect is refused for an account that should have access
App Store Connect does not open to every Apple Account.
3 causes, each with a fixMobile apps
Apple rejected the app under Guideline 4.3, Design: Spam
Guideline 4.3(b) - Design - Spam
Guideline 4.3 is Apple's duplicate rule.
5 causes, each with a fixMobile apps
App Store Connect rejects a screenshot because it has transparency
Images can't include alpha channels or transparencies.
App Store Connect does not accept screenshots that carry an alpha channel or transparent pixels.
2 causes, each with a fix