Size Analysis

Size Analysis helps monitor your mobile app's size in pre-production to prevent unexpected size increases (regressions) from reaching users. Aside from being courteous to your users, a smaller app size helps boost installation and retention rates, especially for customers with limited storage or slower connections.

Getting Started

Accepted Formats: XCArchive (preferred) | IPA

Upload Mechanisms: Fastlane Plugin or Sentry CLI

Uploading With Fastlane

The Fastlane plugin can be used to upload XCArchive or IPA builds to Sentry. On GitHub Actions, Fastlane will automatically detect your build's metadata and include it in the upload. In other Continuous Integration (CI) environments, you may need to manually set metadata values.

1. Configure the Sentry Fastlane plugin (version 1.36.0):

   Ruby

   Copied

   bundle exec fastlane add_plugin fastlane-plugin-sentry
   

2. Set up SENTRY_AUTH_TOKEN in your environment (you can generate a token here)

3. In FastFile, add a call to sentry_upload_build after your build step:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
      build_ios_app(
        scheme: 'YourScheme',
        configuration: 'Release',
      )
      sentry_upload_build(
        org_slug: 'your-org',
        project_slug: 'your-project',
        build_configuration: 'Release' # Adjust to your configuration
      )
   end
   

4. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI

   

The Fastlane plugin automatically detects all build metadata. If needed, the metadata values can be overridden by passing parameters to sentry_upload_build:

lane :upload_to_sentry do
  build_ios_app(
    scheme: 'YourScheme',
    configuration: 'Release',
  )
  sentry_upload_build(
    org_slug: 'your-org',
    project_slug: 'your-project',
    build_configuration: 'Release',
    # Optional metadata overrides:
    head_sha: 'abc123',
    base_sha: 'def456',
    vcs_provider: 'github',
    head_repo_name: 'organization/repository',
    base_repo_name: 'organization/repository',
    head_ref: 'feature-branch',
    base_ref: 'main',
    pr_number: '42'
  )
end

See the Fastlane repo for more information.

Uploading with the Sentry CLI

1. Install the sentry-cli (version 3.1.0)

   We recommend using the latest version for the best possible experience, but at a minimum version 2.58.2 is required.

2. Authenticate the Sentry CLI by following these steps

3. Build your app to create an XCArchive (preferred) or IPA

4. Invoke the following CLI command to trigger the upload:

   Bash

   Copied

   sentry-cli build upload app.xcarchive \
     --org your-org \
     --project your-project \
     --build-configuration Release
   

5. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI

   

Upload Metadata

We use build metadata to organize builds in the UI and ensure correct comparisons.

* required field

Build Configuration

Features such as automatically comparing the head build against the base build will only compare builds of the same build configuration. This is important to consider when setting up Size Analysis in your CI. For example, Release and Debug builds can be drastically different depending on the compiler and linker settings used during the build process. Trying to compare the two would give unexpected results.

Sometimes this is expected though, say you want to test the impact of converting your project to use Bazel (e.g. Release vs Release-Bazel). In this case, it's still possible to perform a manual comparison of builds with different build configurations.

Understanding App Size

Download vs. Install Size

Sentry's iOS app size metric tracks the unencrypted install size of your app on the latest iPhone hardware running the latest iOS version. Since install size is what users see before downloading your app and before deciding if an app should be deleted, it's the most important metric to track and reduce on iOS.

Apps are compressed before they are downloaded, so the actual number of bytes transferred will be lower than the amount of storage taken up by an installed app. Users can see both these numbers, but install size is more prominently displayed.

The install size is what you see when viewing the details for an app on the App Store:

By default, download size will only be displayed if an app is over the Apple determined limit of 200 MB and the user is not on Wi-Fi. Hidden in the iOS Settings app, users can configure the App Store to always warn them of the download size of an app before starting the download, still only when not connected to Wi-Fi.

Users can also review the app's install size in the Settings app.

It's important to reduce install size, because this is what many users see when deciding if an app should be downloaded or what apps to delete.

Regarding App Clips: By default, Sentry measures all content inside the uploaded xcarchives (minus app thinning), which means that if App Clips are included, we will measure and add their impact to the app size. We do this so users can monitor changes to the App Clips on each version, but physical devices do not download App Clips with the apps, so the install and download sizes will be bigger than the ones displayed in TestFlight or the App Store.

App Thinning

App Thinning is Apple's technology that automatically optimizes the delivery of iOS apps to reduce their download size for end users. When your app is uploaded to the App Store, Apple creates device-specific variants that only include the resources needed for each device type. For example, an iPhone SE doesn't need images intended for iPads.

Sentry Size Analysis does not perform any app thinning as part of the analysis, the underlying app is untouched and results shown as-is.

If you want results targeting a specific device type (recommended), apply app thinning before uploading to Sentry. This can be configured via Export Options when building the app. First create an export_options.plist file with the desired device type:

<?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>ad-hoc</string>
<key>team_id</key>
<string>your-team-id</string> <!-- set to your ID -->
<key>thinning</key>
<string>iPhone17,1</string> <!-- set to your device type -->
</dict>
</plist>

And then pass this file to xcodebuild via the -exportOptionsPlist export_options.plist flag when building the app. This will produce a app-thinning.plist file in your build directory with information on the created app variants and where they are located on disk. Pick the appropriate IPA when uploading to Sentry.

If a build is uploaded without first being thinned, you may see multiple copies of your images (ex. different idiom and colorspace values) in your build analysis. We recommend uploading the thinned build to Sentry for the best results.

WatchOS Architectures

WatchOS apps produced by Xcode often contain both arm64_32 and arm64 architectures in a single fat binary. By default Sentry calculates the size of this data as-is, however, your end users will only download whatever architecture is necessary for their device. It's recommended to apply App Thinning before uploading for more representative results.

Code Signature

App bundles contain code signature data within _CodeSignature/ directories. In these you'll find a CodeResources plist file with hashes of every file within the bundle. Similarly, Mach-O binaries contain additional hashes of every page block within its LC_CODE_SIGNATURE load command. This means the size of code signature data will scale linearly with the amount of files in your bundle and size of your binaries.

By default Sentry calculates the size of this data as-is. You may notice differences when comparing against your app downloaded from the App Store. For example, Xcode 26 archives only codesign with SHA256 hashes, but the App Store can use both SHA1 and SHA256 hashes. In other words, App Store downloads of your app may be slightly larger than what's produced by Xcode. This App Store behavior is subject to change at any time.

If you'd like to compare the impact of this on your app, you can re-sign your app before uploading to Sentry:

# Inspect the current code signature
codesign -dvvv '/path/to/your/app.app'

# Re-sign with a new code signature
codesign --force \
  --sign 'Apple Distribution: Your Team (team_id)' \
  --digest-algorithm sha1 \
  --digest-algorithm sha256 \
  '/path/to/your/app.app'

This will force both SHA1 and SHA256 hashes to be used.

App Store Connect File Sizes

App Store Connect has a feature for App File Sizes which provides a report of your app size thinned for various device types. While we strive to be consistent with these numbers, you may see differences between the reported Sentry size and the Apple size. It's important to note that the reported Apple sizes are not consistent with the rest of their tooling, such as the Size Report generated by Xcode, and these are all estimated sizes. You can learn more about these differences here for additional information.

What's Next?

We strongly recommend integrating Size Analysis into your CI pipeline. Follow our guide on getting set up in CI.