.NET MAUI on iOS (macOS + Terminal): Environment Setup, First App, and Fixing Workload Errors

A step-by-step guide to installing, configuring, troubleshooting, and running your first MAUI iOS app entirely from the terminal.

If you’re a .NET developer and want to see your app running on an iPhone simulator quickly, the real work isn’t writing code — it’s getting .NET, Xcode, and the iOS simulator properly aligned.

When I started, I used Microsoft’s official MAUI first app tutorial as the baseline:
https://dotnet.microsoft.com/en-us/learn/maui/first-app-tutorial/intro

This post focuses on the practical macOS setup + troubleshooting so your first build actually works — especially if you hit workload errors like I did.

---

Install .NET SDK (no Homebrew)

curl -LO https://dot.net/v1/dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh
dotnet --info

---

Install MAUI workload (the correct way)

If you try installing maui-ios and see:

Workload installation failed: Workload ID maui-ios is not recognized.

That’s expected in many setups. The right approach is to install the maui workload (it brings iOS pieces with it):

dotnet workload install maui
dotnet workload list

If you still have issues:

dotnet workload update
dotnet workload repair

---

Install Xcode + Simulator Runtime

1. Install Xcode from the App Store

2. Open Xcode once and accept the license

3. Install command line tools:

xcode-select --install

4. Install an iOS simulator runtime:

• Xcode → Settings → Platforms → install an iOS runtime

• Launch Simulator once to confirm it works

---

Fix Xcode location (common build breaker)

Check current path:

xcode-select -p

Set it explicitly:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Verify:

xcodebuild -version

---

🚀 Create Your First MAUI iOS App

Now the fun part.

Create the project

dotnet new maui -n MauiTestApp
cd MauiTestApp

Restore:

dotnet restore

---

List Available iOS Simulators

xcrun simctl list devices

Look for something like:

iPhone 15 (Booted)
iPhone 15 Pro (Shutdown)

---

Run on iOS Simulator

Boot Simulator (if needed):

open -a Simulator

Build + run:

dotnet build -t:Run -f net8.0-ios

---

Stream iOS Simulator logs (super useful for “blank screen” issues)

xcrun simctl spawn booted log stream --style compact --level debug --predicate 'eventMessage CONTAINS[c] "<your message>"'

Replace <your message> with a keyword you log from your app.

---

If Build Fails

90% of the time:

• Xcode path wrong

• Simulator runtime missing

• Workload not installed

Check:

dotnet workload list
xcode-select -p
xcodebuild -version

---

🔍 Viewing iOS Logs (Pro Debugging Tip)

When app runs but something silently fails:

xcrun simctl spawn booted log stream --style compact --level debug --predicate 'eventMessage CONTAINS[c] "<your message>"'

Replace <your message> with a string you log inside your MAUI app.

This is extremely useful for:

• Blank screens

• Startup crashes

• Dependency injection failures

• Native iOS interop issues

---

Closing Thoughts

MAUI iOS development is smooth once the toolchain is aligned:

• .NET SDK

• MAUI workload

• Xcode installed

• Correct xcode-select path

• Simulator runtime available

Once those are validated, building and running from terminal becomes predictable and reliable.

Treat your environment like infrastructure. Verify it once. Then focus on your app.