How to install Xcode 26's Metal Toolchain on CI/CD
Go from confusion to confidence with a step-by-step Swift Concurrency course, helping you smoothly migrate to Swift 6 and fully leverage its features.
As of Xcode 26, the Metal toolchain is no longer included in Xcode’s installation by default. This means that, if your app or one of your dependencies needs to use the toolchain, you will need to install it manually before building your app.
When running your app locally using Xcode, this issue manifests itself as a build error:
The fix is simple enough and, as the error message says, you just need to go to Xcode’s preferences and install the toolchain.
However, if you happen to be using a CI/CD runner that is not provisioned with the Metal toolchain installed, you will get the same error as above, but this time, you will likely not have access to Xcode to be able to install the toolchain.
You might be surprised to learn that this is the case for Xcode Cloud, as I recently discovered the hard way when migrating my CI/CD workflows to use Xcode 26.
So, how can you fix it? Luckily, as suggested by this user on Reddit, the xcodebuild command-line tool has two commands that you can use to download and install the toolchain if it is not already installed:
if xcodebuild -showComponent metalToolchain >/dev/null 2>&1; then
echo "✅ Metal toolchain is installed"
else
echo "❌ Metal toolchain is not installed"
echo "⬇️ Downloading metal toolchain..."
xcodebuild -downloadComponent metalToolchain -exportPath /tmp/metalToolchainDownload/
echo "🧰 Installing metal toolchain..."
xcodebuild -importComponent metalToolchain -importPath /tmp/metalToolchainDownload/*.exportedBundle
fiIf you use Xcode Cloud, I would suggest that you run this as a post clone script.