App thinning ships a smaller app than the one you uploaded, and two different numbers get capped.

What does Apple document about app thinning?

Apple's Xcode Help page, titled What is app thinning? for iOS, tvOS and watchOS, read on 21 October 2026, defines it as the App Store and the operating system optimizing installation by tailoring app delivery to the capabilities of the user's particular device and operating system versions, with minimal footprint. The page splits it into three parts: slicing, bitcode and on-demand resources. One of those three is no longer true, and there is a section below about that.

Slicing is the part that changes what a customer downloads. Apple describes it as creating and delivering variants of the app bundle for different target devices and operating system versions, where a variant contains only the executable architecture and resources needed for that target. You continue to develop and upload full versions of your app, and the App Store creates and delivers the variants. Apple is specific about how you help it: use asset catalogs, so the App Store can select the images, GPU resources and other data appropriate for each variant. Assets that sit loose in the bundle cannot be sliced away.

There is a floor under slicing. Apple notes that sliced apps are supported on devices running iOS and tvOS 9.0 and later, and that otherwise the App Store delivers universal variants. Universal variants also go out through Mobile Device Management, through apps purchased in volume via Apple School Manager or Apple Business Manager, and to anyone downloading through iTunes 12.6 or earlier. That is why App Store Connect shows you a row called Universal next to the per device rows. It is the fallback build, carrying everything.

Two practical points follow. App Store Connect Help states that after you upload a build it goes through app thinning, a process that creates variants of your app for different devices and operating system versions, so this is not something you switch on for store releases. Apple's advanced optimization article is blunter: apps available on the App Store, and apps you distribute to testers using TestFlight, already leverage app thinning. You only have to enable it by hand in two cases, an in-house enterprise app or builds handed to testers outside TestFlight, by exporting for all compatible device variants.

App Store Connect Help, view builds and metadata, read 21 October 2026

What are the current published size limits for an iOS app?

They are in one table, on the App Store Connect Help page called Maximum build file sizes, read on 21 October 2026. Apple asks you to verify that your app, and each Mach-O executable file inside it, does not exceed the maximum file size limits on the supported operating systems. For an iOS or iPadOS app with a minimum deployment target of iOS 9.0 or later, that is 4 GB uncompressed and 500 MB for the executable. The 500 MB carries a footnote: it is for the total of all __TEXT sections in the binary.

Older deployment targets get smaller executable caps, and they are measured differently. An app targeting iOS 7.X through iOS 8.X is held to 60 MB, footnoted as the __TEXT sections in each architecture slice rather than the whole binary. Anything earlier than iOS 7.0 gets 80 MB. Nobody ships those targets now, but the footnotes explain why two numbers that look comparable are not. tvOS 9.0 and later and visionOS 1.0 and later use the same pair as modern iOS, 4 GB and 500 MB. watchOS is capped at 75 MB and macOS at 200 GB, and Apple publishes no separate executable figure for either.

This is the rare case where the figures the internet repeats and the figures on the vendor page agree. The 4 GB and 500 MB caps are the current published ones, worded exactly that way, with the footnotes intact. The place a reader gets caught is not the number, it is which thing the number is measuring.

App Clips are the exception worth knowing, because the cap is an order of magnitude tighter and it is applied after thinning. Apple asks you to verify that the uncompressed main bundle of any App Clip variant, after app thinning, stays under the limit for its minimum deployment target. That is 100 MB with a minimum target of iOS 17 and later, and the 100 MB comes with three conditions: digital invocations only, such as your website or Spotlight search, and not App Clip Codes, QR codes or NFC tags; use in situations where a reliable internet connection is likely; and no support for iOS versions before iOS 17. Miss one of those and you are back to 15 MB for iOS 16 and later, or 10 MB before it.

One escape hatch is on the same page. For iOS, iPadOS, macOS, tvOS and visionOS apps, Apple says you can use Background Assets to host larger assets that are managed separately from your build. watchOS is absent from that list. If you use Apple-hosted Background Assets, Apple also changes what your product page prints: it shows an Up to size that includes any non-localized essential asset packs plus the localized essential packs for the single language with the largest total size.

App Store Connect Help, maximum build file sizes, read 21 October 2026

Which limit applies to the download, and which to the installed app?

The 4 GB cap is on the uncompressed app, which is the installed one. The 200 MB figure is on the compressed download. Apple defines both words in App Store Connect Help, on the page about viewing builds and metadata. The install size is the amount of disk space the app consumes on the customer's device. The download size is the compressed size of the app that is downloaded over the air, using cellular bandwidth or Wi-Fi. Apple's Reducing your app's size article states the same mapping from the other end: in the app size report, the uncompressed size is equivalent to the size of the installed app on the device, and the compressed size is the download size of your app.

The 200 MB is where the consequence sits. App Store Connect Help says that if any of the device variant sizes exceed the 200 MB over the air download limit, a yellow warning icon appears next to the build string in the Builds table and next to the variant size in the App File Sizes table, and that Apple also sends you an email with the same information. Nothing is blocked and nothing is rejected. What changes is the customer's experience: Apple's Reducing your app's size article says that when an app exceeds the limit, users need to connect to a Wi-Fi network to install it. The behaviour on the customer's phone is its own topic, covered in the ios app size limit cellular guide.

To read your own figures: open Apps and select the app, click the TestFlight tab to view all builds, select the platform in the sidebar, then select the app icon or build string in the expanded table under the version number in the Build column. Click the Build Metadata tab and, under General Information, click App File Sizes. A table appears with the different variant sizes, one row per device type plus the Universal row. The Build Metadata page itself shows the compressed file size, essential content size and additional in-app content size. Every figure there belongs to one build, which is why a tidy version vs build number habit saves you from comparing the wrong two rows next month.

The install size also leaves App Store Connect and lands on your product page, in the Information section. Apple adds a detail that explains why two people see different numbers for the same app: the size shown on your product page varies depending on the device viewing the page. On macOS the page shows the universal installation size. On every other platform it shows the installation size for that specific device model. So the figure a customer reads is their own variant, not your worst one.

One warning before you plan a release around a target size. Apple says that when your app is approved for distribution it is encrypted with Digital Rights Management and recompressed, that the file size may therefore be larger than the binary you uploaded, and that the exact final size for your app cannot be determined in advance. A variant that lands just under the limit has not safely cleared it. Leave headroom.

App Store Connect Help, view builds and metadata, read 21 October 2026

How do you get a variant back under the line?

Measure first, and not from the file you think. Apple is explicit that none of the binaries you create for debugging, or upload to the App Store from inside Xcode, are suitable for measuring your app's size. That rules out the APP bundle, the XCARCHIVE and the IPA you upload, because all three carry files customers never download, such as dSYM files for crash reporting. The supported measurement during development is an app size report generated on your Mac: archive the app, export it as an Ad Hoc, Development or Enterprise build, choose all compatible device variants for app thinning in the distribution options, and sign and export. The output folder contains a file named App Thinning Size Report.txt with the compressed and uncompressed size of every variant, plus a universal IPA for older devices and a thinned IPA per variant.

That report is an estimate. Apple says App Store Connect gives the most accurate size information once the app is on the store or in TestFlight, and that it warns you if a variant exceeds the limit for downloading over a mobile internet connection. If you want the report in continuous integration instead of by hand, Apple documents an xcodebuild export with the thinning key set to thin for all variants in the export options property list.

Then the levers, in Apple's own order of effort. Check that your Release configuration still uses the default optimization level, Fastest, Smallest [-Os], because a changed project setting is a common cause of a build that is bigger than expected. Unzip a thinned IPA and look for files that should not be shipping, such as a README added to a target. Move assets into asset catalogs and tag each one with the devices it is for, which is what lets thinning drop it. Keep data in asset files rather than in source code, because that shrinks the binary and lets App Store Connect compress the app more efficiently. After that, formats: Apple names HEIF for images and HEVC for video, and points out that an 8-bit PNG can be a quarter of the size of a 32-bit one.

Two structural moves take content out of the download entirely. On-demand resources group infrequently used files into asset packs that Apple hosts, and Apple states those packs do not become part of your app's initial download or of app updates. Background Assets is the route the size limits page itself points at for larger assets managed separately from the build. Either way the content stays in the app, it just stops arriving in the first download. Note one condition: Apple says that if you distribute outside the App Store, you host on-demand resources yourself.

Updates are a separate size problem with a separate fix. Instead of re-downloading the whole app, the App Store compares prior versions against the new one and builds an update package holding only changed content, comparing everything in the application bundle including the executable, storyboards, nibs and localizations. So avoid touching files you did not mean to change, and keep volatile content in different files from stable content. Apple also warns not to rely on creation and modification dates, because the system updates files only when their content changes, not when metadata does. None of this work costs money, which makes it the cheapest line on any honest reckoning of the cost to publish an app.

App Store Connect Help, maximum build file sizes, read 21 October 2026