A provisioning profile is an Apple-signed configuration file that authorizes a specific app to run on Apple devices by binding together an App ID, one or more signing certificates, a set of entitlements and, for some profile types, a list of permitted device identifiers. In mobile distribution, it is the gatekeeper between a compiled iOS, iPadOS, watchOS, tvOS or macOS app and the devices or channels it may reach, from a developer’s test phone to TestFlight and the App Store.
The operating system checks the profile at installation and launch. If the certificate, App ID, entitlements or device do not match what the profile allows, installation fails or the app refuses to start, which is why profile problems are among the most common obstacles in Apple app builds.
What a provisioning profile contains
Technically, a profile is a property list wrapped in a cryptographic signature from Apple, stored with the extension .mobileprovision on iOS and .provisionprofile on macOS. When an app is built for distribution, the profile is copied into the app bundle as embedded.mobileprovision, so the device can verify it without contacting Apple.
| Field | Content | Why it matters |
|---|---|---|
| App ID | Team ID plus bundle identifier, explicit or wildcard | Defines which app the profile covers |
| Certificates | Development or distribution certificates allowed to sign | Links the profile to a signing identity |
| Entitlements | Capabilities such as push notifications or iCloud | Grants access to protected services |
| Provisioned devices | List of device identifiers, if applicable | Limits installation to known devices |
| Expiration date | Usually up to about one year | Determines when renewal is needed |
A key distinction concerns the App ID type. An explicit App ID matches one bundle identifier and is required for most capabilities, while a wildcard App ID can cover several apps but cannot enable services such as push notifications or in-app purchase.
Types of provisioning profiles
Apple defines profile types by distribution method. Choosing the wrong one is a frequent cause of failed uploads and installations, because each type allows a different audience and requires a different certificate.
| Profile type | Audience | Device list required |
|---|---|---|
| Development | Team members testing on their own devices | Yes |
| Ad hoc | Limited testers outside the store | Yes, within the yearly device limit |
| App Store | App Store and TestFlight distribution | No |
| In-house enterprise | Employees of one organization | No, but only for internal use |
| Developer ID | Mac apps distributed outside the Mac App Store | No |
Development and ad hoc profiles depend on registered devices, and a membership can register a limited number of devices per device family, traditionally 100 per year. The list can be reset only at the start of a new membership year, so teams that test widely usually prefer TestFlight over ad hoc builds.
How code signing uses the profile
Code signing and provisioning work as a pair. The certificate’s private key signs the app binary and its resources, proving who built it, while the profile states what that signed app is allowed to do and where. The entitlements embedded in the signature must be a subset of those granted in the profile.
- The developer creates or downloads a signing certificate from the Apple developer account.
- An App ID is registered and capabilities are enabled for it.
- A profile is generated that combines the App ID, certificate and, if needed, devices.
- The build tool signs the app and embeds the matching profile.
- The device or App Store Connect validates signature, profile and entitlements.
Xcode’s automatic signing performs most of these steps on its own, which suits small teams. Larger teams and continuous integration systems often switch to manual or centrally managed signing, storing certificates and profiles in a secure repository so that every build machine uses the same identities.
Comparison with Android app signing
Android has no direct equivalent to the provisioning profile. An Android app is signed with a developer key, and permissions are declared in the manifest and granted by the user or system, without an Apple-style central authorization file.
| Aspect | Apple platforms | Android |
|---|---|---|
| Signing authority | Apple-issued certificates | Developer-generated keys, or Play App Signing |
| Device restrictions | Device lists for development and ad hoc | None, sideloading allowed by settings |
| Capability control | Entitlements approved through the profile | Manifest permissions and runtime consent |
| Expiry effects | Expired profiles can stop non-store apps | Keys typically valid for decades |
Common errors and how to fix them
Most failures come from mismatches between the four elements: certificate, App ID, entitlements and devices. Error messages in Xcode or on the device usually point to one of them once the profile content is inspected.
- Profile does not include the signing certificate: regenerate the profile after creating or renewing a certificate.
- Entitlement missing from profile: enable the capability on the App ID and download a fresh profile.
- Device not included: register the device identifier and regenerate the development or ad hoc profile.
- App stops launching after a year: renew expired ad hoc or enterprise profiles and redeploy before the date.
- Free personal team builds expire quickly, typically after seven days, so they suit only short experiments.
Apps already downloaded from the App Store are not affected when the distribution certificate or profile later expires, because Apple re-signs store apps. In contrast, enterprise and ad hoc apps depend directly on their profile, so expiry or revocation can disable them for every user at once.
A plain-language summary
A provisioning profile is like a permission slip from Apple that travels inside an app. It says which app this is, who built it, what special features it may use, and sometimes on which exact devices it may be installed.
When someone tries to install or open the app, the iPhone reads the slip. If anything does not match or the slip has expired, the phone refuses to run the app. This keeps unapproved apps off devices, but it also means developers must keep their slips up to date.
An example from practice
A company distributes an internal inspection app to 400 field technicians through enterprise distribution. One morning, every technician reports that the app closes immediately on launch. The mobile team discovers that the in-house provisioning profile expired overnight, because the renewal reminder had gone to a former employee.
The team generates a new profile, re-signs the build and pushes it through the company’s device management system within a few hours. Afterward, it moves certificate and profile ownership to a shared team account, adds expiry checks to the build pipeline that warn 60 days in advance, and evaluates moving the app to private distribution through the store, which would avoid this type of outage altogether.