# Which version of Xcode works with .NET MAUI?

> Independent, auto-updated tracker of which Xcode version each .NET MAUI / .NET for iOS release requires. Last checked 2026-10-01 against the official dotnet/macios release notes. Machine-readable data: https://whichversionofxcodeformaui.com/compat.json

## Current answer

- Status: OK — use the Xcode below, updated together with the workload
- The newest .NET for iOS (27.0.10722, .NET 10) requires Xcode 27.0, which is also Apple's latest release. Update Xcode and your MAUI workloads together, as a pair — updating only one of them breaks iOS builds.
- Required Xcode: 27.0 (any 27.0.x patch is fine)
- .NET: 10; .NET for iOS: 27.0.10722; workload set: 10.0.401.1; .NET SDK: 10.0.401; macOS: 26.6+
- MAUI: SR 11 10.0.110 or later recommended (https://github.com/dotnet/maui/releases/tag/10.0.110)
- Install: dotnet workload install maui --version 10.0.401.1
- Official release notes: https://github.com/dotnet/macios/releases/tag/dotnet-10.0.1xx-xcode27.0-10722
- Xcode 27.2 beta 2 exists but betas are never supported by stable workloads.

## Support matrix (newest release per .NET major)

| .NET | MAUI support | Requires Xcode | macOS | Workload set | .NET for iOS | Released |
|---|---|---|---|---|---|---|
| 11 | preview | 26.6 | 26.2+ | 11.0.100-rc.1.26458.5 | 26.5.12193-net11-rc.1 | 2026-09-08 |
| 10 | supported until 2027-05-11 | 27.0 | 26.6+ | 10.0.401.1 | 27.0.10722 | 2026-09-29 |
| 9 | ended 2026-05-12 | 26.5 | 26.2+ | 9.0.314.3 | 26.5.9002 | 2026-05-21 |
| 8 | ended 2025-05-14 | 16.0 | 14.5+ | - | 18.0.8319 | 2024-12-19 |

## Xcode → workload set lookup (newest stable release requiring each Xcode)

| Xcode | .NET | Workload set | .NET SDK | .NET for iOS | Released |
|---|---|---|---|---|---|
| 27.0 | 10 | 10.0.401.1 | 10.0.401 | 27.0.10722 | 2026-09-29 |
| 26.6 | 10 | 10.0.401 | 10.0.401 | 26.5.10318 | 2026-09-08 |
| 26.5 | 10 | 10.0.300.3 | 10.0.300 | 26.5.10284 | 2026-05-21 |
| 26.5 | 9 | 9.0.314.3 | 9.0.314 | 26.5.9002 | 2026-05-21 |
| 26.4 | 10 | 10.0.203.1 | 10.0.203 | 26.4.10259 | 2026-05-05 |
| 26.4 | 9 | 9.0.313.1 | 9.0.313 | 26.4.9015 | 2026-05-05 |
| 26.3 | 10 | 10.0.202 | 10.0.202 | 26.2.10233 | 2026-04-15 |
| 26.3 | 9 | 9.0.313 | 9.0.313 | 26.2.9008 | 2026-04-15 |
| 26.2 | 10 | 10.0.200 | 10.0.200 | 26.2.10217 | 2026-03-11 |
| 26.2 | 9 | 9.0.312 | 9.0.312 | 26.2.9000 | 2026-03-11 |
| 26.1 | 10 | 10.0.101 | 10.0.101 | 26.1.10502 | 2025-12-09 |
| 26.0 | 10 | 10.0.100 | 10.0.100 | 26.0.11017 | 2025-11-11 |
| 26.0 | 9 | 9.0.311 | 9.0.311 | 26.0.9785 | 2026-02-10 |
| 16.4 | 9 | 9.0.305 | 9.0.305 | 18.5.9219 | 2025-09-09 |
| 16.3 | 9 | 9.0.203 | 9.0.203 | 18.4.9288 | 2025-04-08 |
| 16.2 | 9 | 9.0.202 | 9.0.202 | 18.2.9180 | 2025-02-20 |
| 16.1 | 9 | 9.0.101.1 | 9.0.101 | 18.1.9163 | 2024-11-26 |
| 16.0 | 8 | 8.0.402.1 | 8.0.402+ | 18.0.8303 | 2024-09-26 |

## The rule

- Each .NET for iOS / tvOS / Mac Catalyst / macOS workload release requires exactly ONE Xcode version, compared on major.minor (26.6 and 26.6.1 match; 26.5 and 26.6 do not).
- .NET MAUI itself is a NuGet package; the Xcode requirement comes from the iOS / Mac Catalyst workloads (dotnet/macios) that MAUI builds on.
- The build check is the MSBuild target _ValidateXcodeVersion, error E0191. It runs for builds that produce an app bundle on a Mac (including Pair to Mac builds from Windows).
- Apple ships an Xcode first; Microsoft ships a matching workload days to weeks later. During that gap, a Mac whose Xcode auto-updated can't build MAUI iOS apps.
- The mismatch can happen in either direction: Xcode updated (workload too old), or workloads updated by "dotnet workload install/update" without a pinned version (workload too new).
- Since April 28, 2026, App Store Connect only accepts iOS apps built with Xcode 26 or later and the iOS 26 SDK, so staying on an old Xcode forever is not an option for shipping apps.

## The error

Exact text (platform may be iOS, tvOS, macOS or Mac Catalyst):

    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.

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

## Fixes, in order of preference

1. Diagnose: run "xcodebuild -version", "xcode-select -p", "dotnet --version", "dotnet workload --version" and "dotnet workload --info". Compare the Xcode version with the one required by your installed .NET for iOS release.
2. Match Xcode to your workload: install the required Xcode side by side (https://developer.apple.com/download/all/ or the "xcodes" CLI / Xcodes.app), then either "sudo xcode-select --switch /Applications/Xcode_26.6.app" or build with "-p:XcodeLocation=/Applications/Xcode_26.6.app" (also works as an XcodeLocation environment variable). Rename Xcode.app before first launch, not after.
3. Match your workload to Xcode: install the workload set listed for your Xcode in the lookup table, e.g. "dotnet workload install maui --version 10.0.401". The workload set must belong to your installed .NET SDK feature band (10.0.4xx SDK -> 10.0.4xx workload sets).
4. Pin it: add {"sdk": {"version": "10.0.401", "workloadVersion": "10.0.401.1"}} to global.json so every machine and CI agent installs the same workloads. With a workloadVersion in global.json, "dotnet workload install/update/restore" use it and ignore --version.
5. Stopgap only: <ValidateXcodeVersion>false</ValidateXcodeVersion> in the .csproj (or -p:ValidateXcodeVersion=false) skips the check. Microsoft says other Xcode versions are unsupported "even if there are no build errors". It often works across a minor Xcode bump; it does not make a new Xcode's APIs available.
6. Prevent it: turn off automatic App Store updates on every Mac that builds MAUI apps (System Settings > General > Software Update > Automatic Updates > "Install application updates from the App Store").

## Gotchas

- "dotnet workload update" without --version moves you to the newest workload set, which may require a newer Xcode than you have. "dotnet workload restore" in manifests mode does the same.
- A global.json workloadVersion overrides --version; run the command outside that folder, or edit global.json.
- ~/Library/Preferences/Xamarin/Settings.plist (or .../maui/Settings.plist) with AppleSdkRoot, and the MD_APPLE_SDK_ROOT env var, override xcode-select. Both are deprecated; delete them if the "wrong" Xcode keeps being used.
- New Xcode releases sometimes require a newer macOS (see the "Needs macOS" column). Older Mac hardware can get stuck on an older workload.
- Physical devices: if a test iPhone updates to an iOS version newer than your Xcode's device support, deploys fail even though the build works. Keep test devices in step with Xcode.
- Windows + Pair to Mac (Visual Studio 2026): the Xcode on the remote Mac is what's validated. Rented or shared Macs that auto-update Xcode break Windows builds.
- CI: hosted macOS runners (GitHub Actions, Azure Pipelines) change their default Xcode on their own schedule. Select Xcode explicitly in the pipeline ("sudo xcode-select -s /Applications/Xcode_26.6.app") and pin the workload set in global.json.
- Xcode betas are never supported by a stable workload. Previews of the next .NET usually track a different Xcode than the current stable release.
- Visual Studio for Mac was retired 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.
- .NET MAUI 9 reached end of support on May 12, 2026; .NET MAUI 8 on May 14, 2025. Use .NET MAUI 10 (supported until May 11, 2027).

## Authoritative sources

- .NET for iOS releases (exact Xcode per release): https://github.com/dotnet/macios/releases
- Microsoft's Xcode requirement doc: https://learn.microsoft.com/dotnet/ios/troubleshooting/xcode-requirement
- Workload sets: https://learn.microsoft.com/dotnet/core/tools/dotnet-workload-sets
- XcodeLocation / ValidateXcodeVersion build properties: https://github.com/dotnet/macios/blob/main/docs/building-apps/build-properties.md
- .NET MAUI support policy: https://dotnet.microsoft.com/platform/support/policy/maui
- Apple SDK minimum requirements: https://developer.apple.com/news/upcoming-requirements/
- Apple Xcode release history: https://xcodereleases.com

## About

Maintained by Brad Dean (brad@fweem.com), independent of Microsoft and Apple. Data refreshes automatically every day from the sources above.