Creating an iOS Provisioning Profile: A Comprehensive Guide

Introduction / Why This Matters

Provisioning Profile — a critically important file in the Apple ecosystem that authorizes your app to run on specific devices or in the App Store. Without a properly configured profile, Xcode won't be able to install your app on an iPhone/iPad, even if the project builds without errors. This guide covers the full cycle of creating a profile for development (Development) and distribution (App Store/Ad Hoc) via the Apple Developer Portal and Xcode.

Requirements / Preparation

Before you begin, ensure you have:

1. An Apple ID account enrolled in the Apple Developer Program (paid) or a free developer account.
2. A Mac with Xcode (version 15 or newer) installed and access to Keychain Access.
3. Your project's Bundle Identifier (found in Xcode: Target → General → Identity → Bundle Identifier).
4. For a Development profile: the UDIDs of devices you plan to install on (max 100 for paid accounts).
5. For distribution profiles: a ready Distribution Certificate (App Store or Ad Hoc).

Step 1: Sign in to Apple Developer Portal and Check App ID

All profile operations are performed on the Apple Developer web portal.

1. Go to developer.apple.com and sign in with your account.
2. Navigate to the Certificates, Identifiers & Profiles section (or find it via search).
3. In the left menu, select Identifiers → App IDs.
4. Find the App ID that matches your app's Bundle Identifier (e.g., com.example.myapp). If it doesn't exist, click + to create one:
   • App ID Description: Any description (e.g., "MyApp Development").
   • Bundle ID: The exact value from Xcode. Select the App type.
   • Configure other options (Capabilities) as needed (Push Notifications, Sign In with Apple, etc.).
5. Remember the App ID Prefix (Team ID) and Bundle ID — you'll need them later.

Step 2: Create a Developer Certificate (If Missing)

Provisioning Profiles are always tied to a certificate. A Development profile requires a Development Certificate.

1. In the Certificates section, click +.
2. Select Apple Development (formerly iOS App Development) → Continue.
3. Generate a CSR (Certificate Signing Request) on your Mac:
   • Open Keychain Access (Applications → Utilities).
   • From the menu, choose Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority....
   • Enter your email, common name (e.g., "iPhone Developer: First Last (TeamID)"), select "Save to disk" and "Let me specify key pair information". Click "Continue" and save the .certSigningRequest file.
4. Upload the CSR file to the Apple portal → Continue → Download.
5. Double-click the downloaded .cer file to install it in Keychain Access under "My Certificates". Ensure the certificate has a small triangle to reveal the private key.

::in-article-ad::

Step 3: Add Devices (Development Profile Only)

If you're creating a profile for testing on real devices, you must register them first.

1. In the Devices section (on the Apple Developer portal), click +.
2. Enter a Device Name (e.g., "iPhone 15 Pro Max") and UDID.
   • How to get the UDID: Connect the device to your Mac, open Xcode → Window → Devices and Simulators. Select the device from the list, copy the long identifier (Identifier) or click "Copy UDID".
3. Repeat for each test device. Note the limit (100 for paid accounts).

Step 4: Create a Provisioning Profile

Now we'll combine all components into a profile.

1. In the Profiles section, click +.
2. Select the profile type:
   • iOS App Development — for testing on registered devices.
   • App Store — for App Store distribution (no device selection).
   • Ad Hoc — for distribution outside the App Store (up to 100 devices per year).
   • Enterprise — for internal company distribution (requires Enterprise Program).
3. Click Continue.
4. Select the App ID from the list (the one created in Step 1) → Continue.
5. Select certificate(s): Check the box for your Development Certificate (or Distribution for App Store/Ad Hoc). You can select multiple → Continue.
6. Select devices (only for Development and Ad Hoc): Choose all devices you want to install the app on → Continue.
7. Name the profile: e.g., MyApp_Dev_2026 → Generate.
8. Download the resulting .mobileprovision file and double-click to install it. The file will automatically be added to Xcode (Xcode → Settings → Accounts → select your Apple ID → Manage Certificates).

Step 5: Configure Xcode Project and Build

After installing the profile, bind it to your project.

1. Open your project in Xcode.
2. Select the Target → General tab.
3. In the Signing & Capabilities section:
   • Team: Select your team (Apple ID).
   • Bundle Identifier: Must exactly match the Bundle ID from the selected App ID.
   • Provisioning Profile: If Xcode didn't select the profile automatically, click the current value (e.g., "Automatically manage signing") and choose the correct profile from the dropdown.
   • Signing Certificate: Should match the profile type (e.g., "Apple Development" for a Development Profile).
4. Important: If you turn off "Automatically manage signing", ensure you select both fields: Provisioning Profile and Signing Certificate.
5. Select a Build for a real device (not a simulator). On successful build, Xcode will sign the app with the selected profile.

Verify the Result

1. Install on device: Connect your iPhone/iPad to your Mac. In Xcode, select the device as the build target (Run). The app should install without errors.
2. Check the profile on the device: On the device, go to Settings → General → VPN & Device Management (or Profiles). You should see the installed developer profile with your App ID's name.
3. For App Store: After building with an App Store profile, the archive (.xcarchive) should successfully validate (Product → Archive → Validate App) without signing errors.

Common Issues

Error: No profiles for 'com.example.myapp' were found

• Cause: The Bundle Identifier in your Xcode project doesn't match any App ID that has a profile.
• Fix: Check the Bundle Identifier in Target → General. Ensure an App ID with that exact value exists in Apple Developer Portal. Recreate the profile, selecting the correct App ID.

Error: Provisioning profile "..." doesn't include the device

• Cause: Your device's UDID is not included in the Development/Ad Hoc profile.
• Fix: Add the device in the Devices section of the Apple Developer Portal, then edit (Edit) the existing profile to include the new device, and reinstall the updated .mobileprovision file.

Error: The app is not authorized to use the specified entitlement

• Cause: A Capability (e.g., Push Notifications, App Groups) is enabled in your project but not activated for the App ID on the portal.
• Fix: In Apple Developer Portal, open the relevant App ID → Edit → enable all Capabilities used in Xcode (Signing & Capabilities). Then recreate the provisioning profile.

Profile doesn't appear in Xcode

• Cause: The .mobileprovision file wasn't installed (double-clicked) or was installed for a different account/team.
• Fix: Ensure you're signed into Xcode (Settings → Accounts) with the same Apple ID used on the portal. Reinstall the profile by double-clicking it. Restart Xcode.

Profile expired

• Cause: Profiles (both Development and Distribution) are valid for 1 year from creation. Certificates also have expiration dates.
• Fix: In the Certificates, Identifiers & Profiles portal section, check expiration dates. To renew, create a new profile (delete the old one). If you change certificates, the old profile becomes invalid — you'll need to create a new one tied to the new certificate.