Which version of Xcode works with .NET MAUI?

The rule

Support matrix

The newest .NET for iOS release for each .NET version, and the Xcode it requires. Data comes from the official release notes.

Find your pair: "I have Xcode X. Which workload set do I install?"

Use this table when you can't (or don't want to) change Xcode. Each row is the newest stable workload set that supports that Xcode version. The workload set must match your installed .NET SDK band: a 10.0.4xx SDK can only install 10.0.4xx workload sets. Check yours with dotnet --version.

Then run: dotnet workload install maui --version <workload set>. To pin that choice, see fix 4.

The error you're probably seeing

error : This version of .NET for iOS (26.2.10197) requires Xcode 26.2. The current version of Xcode is 26.3. Either install Xcode 26.2, or use a different version of .NET for iOS. See https://aka.ms/xcode-requirement for more information.

The platform in the message can also be Mac Catalyst, tvOS or macOS. Older workloads show a different wording:

This version of Microsoft.iOS requires the iOS 18.4 SDK (shipped with Xcode 16.3). The current version of Xcode is 16.2.

Read it like this: the workload you have installed (the number in parentheses) needs Xcode A, but the selected Xcode is B. Either select Xcode A, or install the workload that goes with B.

How to fix it

1. See which pair you actually have

   xcodebuild -version          # the Xcode the build will use
   xcode-select -p              # where it lives
   dotnet --version             # .NET SDK (decides which workload sets you can install)
   dotnet workload --version    # installed workload set
   dotnet workload --info       # exact iOS / Mac Catalyst workload versions

   Find your workload in the table above or in the release notes to see which Xcode it needs.
2. Match Xcode to your workload (usually the easiest fix) You can have several Xcode versions installed side by side. Download the one you need from Apple Developer Downloads, or use xcodes / Xcodes.app. Give each copy its own name, like Xcode_26.6.app, before you open it for the first time. Renaming it afterwards causes strange problems. Then either switch the system-wide Xcode:

   sudo xcode-select --switch /Applications/Xcode_26.6.app

   or pick the Xcode for a single build without changing the system default:

   dotnet build -f net10.0-ios -p:XcodeLocation=/Applications/Xcode_26.6.app

   XcodeLocation also works as an environment variable, which is handy on CI.
3. Match your workload to Xcode Look up your Xcode in the table above and install that workload set:

   dotnet workload install maui --version 10.0.401

   If you need a workload set from a newer SDK band, install that .NET SDK first.
4. Pin it so it stays fixed Add a global.json to the repo so every machine and CI agent uses the same SDK and workloads:

   {
     "sdk": {
       "version": "10.0.401",
       "workloadVersion": "10.0.401.1"
     }
   }

   With this file in place, dotnet workload install, update and restore use the pinned version and ignore --version. Commit this file and update it whenever you move to a new Xcode.
5. Skip the check stopgap only

   <PropertyGroup>
     <ValidateXcodeVersion>false</ValidateXcodeVersion>
   </PropertyGroup>

   or -p:ValidateXcodeVersion=false on the command line. Developers report this usually works when the Xcode version is only one minor release off, including App Store uploads. But Microsoft says using a different Xcode is unsupported "even if there are no build errors", and it doesn't give you any of the new Xcode's APIs. Remove it once matching support ships.
6. Prevent it On every Mac that builds MAUI apps, turn off System Settings → General → Software Update → Automatic Updates → Install application updates from the App Store. When an update is due, update Xcode and the workload together, using this page.

Gotchas

dotnet workload update can break you too

Without --version or a pinned global.json, it jumps to the newest workload set. That set may need a newer Xcode than you have. In "manifests" update mode, dotnet workload restore does the same thing. Check your mode with dotnet workload config --update-mode.

Hidden settings can override xcode-select

~/Library/Preferences/Xamarin/Settings.plist and ~/Library/Preferences/maui/Settings.plist (the AppleSdkRoot key), and the MD_APPLE_SDK_ROOT environment variable, all take priority over xcode-select. They're leftovers from Visual Studio for Mac and are deprecated. If the build keeps finding the "wrong" Xcode, delete them.

Xcode needs a minimum macOS

Some new Xcode versions need a newer macOS (see the "Needs macOS" column). If your Mac can't run that macOS, you're stuck on an older workload until you get new hardware.

Physical test devices

If a test iPhone updates to an iOS version newer than your Xcode supports, deploying to it fails even though the build succeeds. Keep test devices in step with Xcode, or turn off their automatic updates too.

Windows + Pair to Mac

When you build from Visual Studio on Windows, the check runs against the Xcode on the remote Mac. Rented and shared build Macs that auto-update Xcode will break your Windows builds without warning. Find out which Xcode the Mac has and match your workloads to it.

CI runners change Xcode on their own schedule

Hosted macOS images (GitHub Actions, Azure Pipelines) change their default Xcode without warning you. In the pipeline, select Xcode explicitly (sudo xcode-select -s /Applications/Xcode_26.6.app or XcodeLocation) and pin the workload set in global.json.

Xcode betas and .NET previews

Stable workloads never support Xcode betas, so install betas side by side and don't select them. Previews of the next .NET version often need a different Xcode than the current stable release.

Visual Studio for Mac is gone

Microsoft retired it on August 31, 2024. On a Mac, use VS Code with the .NET MAUI extension, or JetBrains Rider. Both use the same command-line workloads and Xcode selection described here.

Old MAUI versions are out of support

.NET MAUI 8 support ended on May 14, 2025, and MAUI 9 support ended on May 12, 2026. MAUI 10 is supported until May 11, 2027 (policy). Also, an old MAUI version can't produce App Store builds once it no longer supports a current Xcode.

How long does the gap last?

The number of days between Apple releasing an Xcode version and Microsoft shipping a .NET for iOS release that supports it. During this gap, the safe choice is to wait.

FAQ

About this data

A scheduled job reads the dotnet/macios release notes once a day. Every release states "Xcode X is required with this release", along with the workload set and minimum macOS. The job also reads Apple's Xcode release history from xcodereleases.com, so it can tell when Apple has shipped an Xcode that .NET doesn't support yet. Last checked: Oct 6, 2026.

Microsoft's own explainer is Xcode requirement – .NET for iOS. If this page and the release notes ever disagree, the release notes win.

I built this site when MAUI first came out, because Xcode auto-updates kept breaking builds. I have no affiliation with Microsoft or Apple. I'm just a big fan of MAUI, and I want it to be easy for other developers to know whether it's safe to update.

Need help?

Do you need help with a MAUI project, or with moving a Xamarin app to MAUI? As a mobile consultant, I've helped companies like Bain, EY, IMSA, and the IRS build apps in Xamarin and MAUI over the last decade. Episode 91 of the Microsoft Xamarin Podcast was about my work on the LivePerson mobile app.

I can help with anything from a one-hour screen-share session to putting together a team that builds a full mobile app and .NET backend: brad@fweem.com