> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modaal.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Set up Xcode
> Modaal builds and runs your iOS app with Apple's Xcode. This guide takes you from zero to a working setup — install Xcode, download the iOS simulators, and let Modaal confirm everything's ready.
**Xcode** is Apple's development environment for building and running iOS apps. Modaal drives it for you behind the scenes — you never have to write Swift in Xcode or wire up a project there. You just need it installed, opened once, and with the iOS simulators downloaded. Modaal does the rest.
## Before you start
Xcode only runs on macOS. A reasonably recent Mac (Apple Silicon recommended) makes builds much faster.
Xcode plus the iOS simulators are large. Check under **→ System Settings → General → Storage** and free up space first if you're tight.
Xcode is a multi-gigabyte download, and the iOS simulators download separately on first launch. Plan for a coffee break.
You only need one to run on a **real iPhone** or to publish to TestFlight / the App Store. The simulator needs nothing.
***
## Open the Xcode setup panel in Modaal
Everything is driven from one place inside Modaal. Click your **profile avatar** in the top-right corner to open the **User Menu**, then choose **Set up Xcode**.
Keep this panel open while you work through the steps below. After each step you'll come back to it and press **Check** / **Re-check** to let Modaal re-detect your setup.
The panel reports one of three states:
| Status | What it means | What to do |
| ----------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 🔴 **Not detected** | Modaal can't find any Xcode installation. | Install Xcode — [Step 1](#step-1). |
| 🟠 **Attention needed** | Xcode is installed, but it isn't finished — usually the iOS simulators haven't been downloaded yet. | Open Xcode and download simulators — [Step 2](#step-2). |
| 🟢 **Installed** | Xcode is installed, set up, and has iOS simulators. You're ready to build. | Nothing — you're done. |
***
Step 1 — Install Xcode
If the panel says **Not detected**, Xcode isn't installed yet.
Install Xcode from either source:
The easiest option. Search for **Xcode**, click **Get**, and it installs and updates automatically.
Download a specific Xcode version directly. Useful if you need an exact release. Sign in with a free Apple Account.
Xcode is a large download (15+ GB) and can take a while to install — let it finish completely before moving on.
For the latest features — **iOS 26**, the **Liquid Glass** design system, and the newest simulators — install **Xcode 26 or newer**.
***
Step 2 — Open Xcode once and download the simulators
This is the step that trips most people up. **Installing Xcode is not enough** — you have to launch it once so it can finish its own setup and download the iOS simulators. Until you do, Modaal shows **Attention needed**:
Open **Xcode** from your Applications folder. The first time it runs, it asks you to agree to the **Xcode and Apple SDKs Agreement**. Read it, then click **Agree** (you'll be asked for your Mac password).
Xcode then offers to install platform components. Make sure **iOS** is checked and click **Download & Install**. You can leave watchOS, tvOS, and visionOS unchecked — Modaal only needs **iOS** to build and run iPhone apps.
If Xcode doesn't show this screen on launch, you can trigger it any time from **Xcode → Settings… → Components**, then download an **iOS** simulator runtime.
The iOS simulator runtime is several gigabytes and downloads in the background. You can watch progress in Xcode's **Downloads** window.
When the download completes, the runtime shows a checkmark and Xcode opens its welcome window. Xcode is now fully set up.
You can quit Xcode now — Modaal launches it on its own when it needs to build.
***
Step 3 — Re-check in Modaal
Go back to Modaal's **Set up Xcode** panel and click **Re-check**. Modaal probes your installation and, when everything's in place, switches to **Installed** (green) and lists the iOS simulators it found.
That's it — you can now ask Modaal to build and run your app, and it'll launch it on the iOS simulator for you.
You can also re-validate from the User Menu via **Run system check**, which re-checks Xcode along with Modaal's other prerequisites.
***
Have more than one Xcode installed?
If you keep several Xcode versions (for example a stable release and a beta), Modaal lists each one and marks which is **active** — the one macOS will use for builds. To switch, click **Set as active** on the version you want.
macOS asks for your administrator password to make the switch (it runs Apple's `xcode-select` under the hood). If the button ever fails, the panel shows the exact command you can run yourself in **Terminal**:
```bash theme={null}
sudo xcode-select -s /path/to/Xcode.app/Contents/Developer
```
***
## Troubleshooting
You almost certainly skipped [Step 2](#step-2). Installing Xcode is not enough — open it once, accept the license, and download an **iOS** simulator runtime from **Xcode → Settings… → Components**. Then click **Re-check** in Modaal.
The simulator runtime hasn't been downloaded. In Xcode, go to **Settings… → Components**, download an **iOS** runtime, wait for it to finish, then **Re-check** in Modaal.
On recent Xcode versions the simulator viewer can't launch when **Xcode is installed on an external or ownership-disabled volume**. Move Xcode to your internal **/Applications** folder, or re-enable ownership on the volume with `sudo diskutil enableOwnership `. The build itself still ran — this only affects showing the window.
Make sure you entered the correct **administrator** password. As a fallback, copy the `sudo xcode-select -s …` command the panel shows and run it directly in **Terminal**.
Xcode plus simulators can easily use 30–50 GB. Remove old simulator runtimes you don't need from **Xcode → Settings… → Components**, and check **→ System Settings → General → Storage** for other large items.
**Still stuck?** Join our [community on Discord](https://discord.gg/KyQzDXxgU3) — we're happy to help you get set up.