Skip to content
Guide

How to upload a build to TestFlight from your Mac

By Senthil Kumar P · Updated · 7 min read

Short answer

To upload a build to TestFlight from a Mac, archive the app in Xcode and choose Distribute App › App Store Connect in the Organizer, or drag the .ipa into Apple's Transporter app. To do it from the command line, export the archive with xcodebuild -exportArchive using an export options plist with destination set to upload and an App Store Connect API key. VenelX Studio does the upload from your Mac with one click and then manages TestFlight groups and App Review.

Before you upload

Every method needs the same things:

  • An Apple Developer Program membership and an app record in App Store Connect with a matching bundle ID.
  • A build number (CFBundleVersion) higher than any build you've already uploaded for that version.
  • Distribution signing: automatic signing in Xcode, or a distribution certificate and App Store provisioning profile.
  • If your app uses no non-exempt encryption, set ITSAppUsesNonExemptEncryption to NO in Info.plist to skip the export-compliance question for every build.

1. Xcode Organizer (easiest, one-off uploads)

  1. Choose a generic iOS device or Any iOS Device as the run destination.
  2. Product › Archive. The Organizer opens when the archive finishes.
  3. Select the archive and click Distribute App.
  4. Choose TestFlight & App Store (or TestFlight Internal Only for internal testers), and follow the prompts.

Good for occasional releases; not something you can hand to a teammate who doesn't have your Mac.

2. Transporter (upload an existing .ipa)

Apple's free Transporter app on the Mac App Store uploads an .ipa you already exported. Sign in with your Apple ID, drag the file in and click Deliver. Useful when someone else built the IPA.

3. xcodebuild with an App Store Connect API key (scriptable)

Archive, then export straight to App Store Connect. An API key avoids Apple ID passwords and two-factor prompts.

xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
  -destination 'generic/platform=iOS' -archivePath build/App.xcarchive archive

ExportOptions.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>app-store-connect</string>
  <key>destination</key>
  <string>upload</string>
</dict>
</plist>
xcodebuild -exportArchive -archivePath build/App.xcarchive \
  -exportOptionsPlist ExportOptions.plist -exportPath build/export \
  -allowProvisioningUpdates \
  -authenticationKeyPath ~/keys/AuthKey_ABC123XYZ.p8 \
  -authenticationKeyID ABC123XYZ \
  -authenticationKeyIssuerID 00000000-0000-0000-0000-000000000000

On Xcode versions before 15.3 the method is named app-store. This is what most CI setups (and fastlane's pilot) wrap.

4. VenelX Studio (one click, from any browser)

VenelX Studio runs the build on your Mac and uploads it through the App Store Connect API, with the API key kept in the Mac's Keychain. From studio.venelx.com your team can then:

  • add the build to TestFlight groups for internal and external testers,
  • submit it for App Review with release notes checked against Apple's limits,
  • turn on a 7-day phased release, with an approval step before production if you want one.

Nobody else needs a copy of the key, and nobody needs to sit at the Mac.

Which should you use?

MethodBest forNeeds someone at the Mac?
Xcode OrganizerOccasional, manual releasesYes
TransporterUploading an IPA someone else builtYes
xcodebuild + API keyScripts and CI pipelinesNo, once scripted
VenelX StudioTeams releasing from a shared Mac miniNo

Common upload errors

  • "The bundle version must be higher than the previously uploaded version": increase CFBundleVersion and archive again.
  • "No profiles for ... were found": add -allowProvisioningUpdates with an API key, or install the App Store provisioning profile.
  • Build stuck in Processing: processing time varies; if it lasts hours, check your email for a rejection from App Store Connect, such as a missing privacy usage description.

Questions and answers

How long does a TestFlight build take to appear?

After upload, App Store Connect processes the build, which usually takes a few minutes and sometimes longer. The build appears in TestFlight once processing finishes, and external testers need Beta App Review for the first build of a version.

Can I upload to TestFlight without opening Xcode?

Yes. Use Apple's Transporter app, xcodebuild -exportArchive with an App Store Connect API key, or a tool such as VenelX Studio that uploads through the App Store Connect API.

Why does my upload fail with a version or build number error?

Every upload needs a build number (CFBundleVersion) higher than any build already uploaded for that version. Increase the build number and archive again.

Put your Mac to work.

Create your account, install the Mac app and approve your Mac. Your first build can run in minutes.

Free sign-up. Paid plans, billed yearly. 14-day money-back guarantee. No per-build or per-minute fees.