Unity iOS Build Guide: Xcode, Signing and Common Errors

Building a Unity game for iPhone is a two-stage process that catches almost everyone the first time. Unity doesn’t produce an app directly. It generates an Xcode project, and Xcode compiles, signs and installs it. Most iOS build problems are really Apple signing problems wearing a Unity costume. This Unity iOS build guide covers what you need, the Player Settings that matter, building to your own iPhone, code signing explained in plain terms, TestFlight and App Store uploads, and fixes for the most common Xcode errors, in Unity 6.

What You Need

• A Mac with a recent macOS and Xcode from the Mac App Store. Apple only allows signing and uploading iOS apps from Xcode. Check Unity’s release notes for the Xcode version your Unity 6 release supports; a much newer or older Xcode can cause build failures.
• The iOS Build Support module in Unity Hub (Installs > your Unity version > Add modules).
• An Apple Account. A free account lets you install builds on your own device for testing (they expire after 7 days). Publishing to TestFlight or the App Store needs the Apple Developer Program ($99 per year).
• An iPhone or iPad and a cable. The Simulator works for quick checks, but performance and some features only make sense on a real device.

You can develop the whole game on Windows and only move to a Mac for the build step. Many developers keep the project in Git and pull it onto a Mac (or a cloud Mac) for iOS builds. See our Git setup guide.

Player Settings for iOS

Switch the platform first: File > Build Profiles, select iOS, and click Switch Platform (this reimports textures for iOS and can take a while on big projects). Then open Player Settings and go through these:

Setting	Where	What to set
Bundle Identifier	Other Settings > Identification	Reverse-domain, unique and permanent, e.g. com.yourstudio.yourgame
Version / Build	Other Settings > Identification	Version shown to players (1.0.0); Build must increase with every upload
Signing Team ID	Other Settings > Identification	Your Apple team ID, so Xcode signs automatically
Automatically Sign	Other Settings > Identification	On, for most people
Target minimum iOS Version	Other Settings > Configuration	Leave at Unity’s default unless a plugin needs higher
Camera / Microphone / Location Usage Description	Other Settings > Configuration	A sentence explaining why, required if your game or any plugin uses it
Orientation	Resolution and Presentation	Portrait, landscape, or auto-rotation with allowed orientations
App icons and Launch screen	Icon / Splash Image	All required icon sizes; a simple launch screen
Graphics APIs	Other Settings > Rendering	Metal (the only option on modern iOS)

The Bundle Identifier is the app’s permanent identity on the App Store. Pick it carefully: you can’t change it for a published app. Missing usage descriptions are a top reason for App Store rejection, and they can also crash the app the first time it asks for permission.

Build the Xcode Project

1. In Build Profiles, make sure your scenes are in the Scene List.
2. For the first build, leave Development Build ticked if you want profiler and debugging support on the device.
3. Click Build and choose an empty folder, such as Builds/iOS. Unity generates the Xcode project there.
4. On later builds into the same folder, Unity asks whether to Replace or Append. Append is faster and keeps changes you made in Xcode; Replace starts clean. Use Replace if something strange is happening.

Open the result in Xcode. If the folder contains a .xcworkspace file, open that, not the .xcodeproj. A workspace means CocoaPods dependencies are involved (common with ads, analytics and Firebase plugins), and opening the project alone gives “module not found” errors.

Build and Run does all of this in one step if Xcode is set up and a device is connected, which is handy once signing works.

Code Signing in Plain English

Apple only lets an app run on a device if it’s signed by a known developer for that specific app and device. Four pieces are involved:

• Certificate: proves who you are. It lives in your Mac’s Keychain.
• App ID: registers your Bundle Identifier with Apple.
• Device: for development builds, the test iPhone must be registered.
• Provisioning profile: ties the certificate, App ID and devices together.

With Automatically manage signing ticked in Xcode (the default when Unity’s Automatically Sign is on), Xcode creates and renews all of these for you. In Xcode, select the Unity-iPhone target, open Signing & Capabilities, tick automatic signing, and pick your Team. Sign in with your Apple Account in Xcode > Settings > Accounts if no team appears. For 90% of indie projects, that’s all there is.

Manual signing (choosing specific certificates and profiles) is mostly needed for build servers and cloud builds.

Run on Your iPhone

1. Connect the iPhone and unlock it. Tap Trust when asked.
2. On iOS 16 and later, enable Developer Mode: Settings > Privacy & Security > Developer Mode, then restart the phone. The option appears after the device has been connected to Xcode.
3. In Xcode, choose the phone as the run destination at the top of the window and press Run (the play button).
4. With a free Apple Account, the first launch is blocked as an “Untrusted Developer”. Go to Settings > General > VPN & Device Management, tap your developer profile and trust it.

Xcode’s console shows the same Debug.Log output you see in Unity, which is the first place to look if the app crashes on launch. For a development build you can also attach the Unity Profiler over the network to see real device performance.

TestFlight and the App Store

1. In App Store Connect (appstoreconnect.apple.com), create a new app with the same Bundle Identifier.
2. In Unity, untick Development Build, raise the Build number, and build again.
3. In Xcode, set the destination to Any iOS Device (arm64), then choose Product > Archive.
4. When the Organizer window opens, select the archive and click Distribute App > App Store Connect. Xcode signs and uploads it.
5. After processing (usually 10–30 minutes), the build appears under TestFlight. Add internal testers (your team) immediately, or external testers after a short beta review.
6. When it’s ready, fill in the store listing (screenshots, description, age rating, privacy details), attach the build to a version, and Submit for Review.

Two things Apple checks that Unity developers often miss: the privacy manifest (Unity includes one for the engine; third-party SDKs must ship their own, so keep plugins up to date) and export compliance. If your game uses only standard HTTPS, you can avoid the encryption question on every upload by adding ITSAppUsesNonExemptEncryption = NO to Info.plist, for example with a small post-build script.

Building Without a Mac

If you only have Windows, you still have options:

• Unity Build Automation (Unity’s cloud build service) builds iOS from your repository on Unity’s Macs. You upload a signing certificate (.p12) and a provisioning profile, which you can create on the Apple Developer website. It’s paid per build minute after any free allowance.
• Rented cloud Macs (several providers rent remote macOS machines by the hour or month) let you run Xcode remotely.
• A second-hand Mac mini is often the cheapest long-term option if you’ll ship updates regularly.

Uploading to the App Store still requires a signed build, but you don’t have to own a Mac to produce one.

Common Xcode and iOS Build Errors

“Signing for ‘Unity-iPhone’ requires a development team”

Select the Unity-iPhone target > Signing & Capabilities and choose your Team. To avoid doing this after every build, enter your Signing Team ID in Unity’s Player Settings.

“No profiles for ‘com.yourstudio.yourgame’ were found”

Automatic signing is off, or the Bundle Identifier is already registered to another team. Turn on automatic signing, or change the Bundle Identifier to one your team owns. Free accounts can’t use some capabilities (like push notifications), which also triggers this.

“Module ‘FirebaseCore’ not found” or other missing modules

You opened the .xcodeproj instead of the .xcworkspace, or CocoaPods didn’t run. Open the workspace. If it’s missing, install CocoaPods and run pod install in the build folder, or use the External Dependency Manager’s iOS resolver in Unity.

“Untrusted Developer” when opening the app

Trust your profile in Settings > General > VPN & Device Management. This is normal for free-account builds.

App crashes immediately on launch

Read Xcode’s console output. Frequent causes: a missing usage description (the app is killed the moment it asks for camera or microphone access), code stripping removing something used by reflection (add a link.xml or lower Managed Stripping Level), or a plugin built for the wrong architecture.

“The app’s Info.plist must contain an NSCameraUsageDescription key”

A plugin references the camera API even if your game doesn’t. Add a usage description in Player Settings, or remove the unused plugin.

Upload rejected for a duplicate or lower build number

Every upload needs a higher Build number than the last, even if the Version stays the same. Raise it in Player Settings and rebuild.

Build fails after upgrading Unity or Xcode

Build with Replace (not Append) into a fresh folder, update plugins, and check the Unity release notes for the supported Xcode version. If you upgraded the project itself, our Unity 6 upgrade guide lists the usual breaking changes. Android has its own set of build problems, covered in our Gradle build failed guide.

FAQ