Upgrading Xcode Versions - codepath/ios_guides GitHub Wiki

Overview

It is common to need more than one Xcode version on the same Mac — for example, to keep building an app against a stable release while trying a new beta, to debug on an older iOS simulator runtime that a newer Xcode no longer ships, or to match the Xcode version used by a CI machine or a teammate. macOS supports having several Xcode.app bundles side by side, and the xcode-select tool decides which one the command-line developer tools (xcrun, xcodebuild, simctl, clang, etc.) use at any moment.

See Troubleshooting Xcode Issues for general "Xcode is in a bad state" recovery steps.

Install a second Xcode side by side

  1. Sign in at developer.apple.com/download/all with your Apple Developer account and download the .xip (or .dmg for very old releases) for the Xcode version you want. The "More" / "All downloads" page is the canonical source for older and beta releases; the Mac App Store usually only offers the current stable version. The community-maintained xcodereleases.com catalog links directly to each Apple-hosted download if you need to find a specific build number.

  2. Double-click the .xip to expand it into an Xcode.app bundle next to the file. Do not open it yet.

  3. Rename the freshly extracted bundle to something descriptive before moving it into /Applications (so it does not collide with the Xcode you already have). For example:

    mv ~/Downloads/Xcode.app ~/Downloads/Xcode-16.0.app
sudo mv ~/Downloads/Xcode-16.0.app /Applications/

  4. Launch the renamed app once from Finder so that macOS verifies it and Xcode installs its bundled components. Accept the license prompt if it appears.

You can repeat this for as many versions as you like. A common layout is Xcode.app (the version you use day-to-day) plus Xcode-beta.app and one or two pinned older releases (e.g. Xcode-15.4.app).

Switch which Xcode the command-line tools use

The xcode-select tool stores the path to one "active" developer directory that xcrun, xcodebuild, and friends consult.

# Inspect the active developer directory
xcode-select -p

# Point command-line tools at a specific Xcode
sudo xcode-select -s /Applications/Xcode-16.0.app/Contents/Developer

# Verify
xcodebuild -version

For a single command — handy in CI scripts or when you just want to build once with a non-default Xcode without changing the system-wide setting — set the DEVELOPER_DIR environment variable instead. It takes precedence over xcode-select for that invocation:

DEVELOPER_DIR=/Applications/Xcode-16.0.app/Contents/Developer xcodebuild -version

The Xcode GUI is independent of this setting — opening a .xcodeproj by double-clicking it launches whichever Xcode is associated with the file type (typically the most recently used one), regardless of what xcode-select points to.

After switching to a freshly installed Xcode, run its first-launch installer once so it can lay down required components:

sudo xcodebuild -runFirstLaunch

Install additional simulator runtimes

A new Xcode normally ships with the matching iOS simulator runtime built in, but older OS runtimes (iOS 17 simulators in Xcode 16, etc.) must be downloaded separately.

  • From the GUI: choose Xcode > Settings… (called Preferences on macOS 12 and earlier), open the Platforms tab (called Components in Xcode 14 and earlier), and click Get next to the runtime you need.

  • From the command line, after downloading the runtime .dmg from the same developer.apple.com/download/all page:

    xcrun simctl runtime add ~/Downloads/iOS_17.5_Simulator_Runtime.dmg

    xcrun simctl runtime list shows what is installed; xcrun simctl runtime delete <identifier> removes one.

Useful third-party tools

If you frequently swap between Xcode versions, the community-maintained xcodes CLI (and its companion Xcodes.app) automates the download / rename / install / select steps above and reads a .xcode-version file in a project root so different repositories can pin different toolchains. It still downloads from Apple's servers and still requires an Apple Developer account.

References

Hello Manh Okne

⚠️ **GitHub.com Fallback** ⚠️