Skip to main content

Understanding iOS framework size

The Mapbox Maps SDK for iOS is a complex and powerful framework, but it only contributes 3–4 megabytes to the ultimate size of your application. This guide suggests a few strategies for reducing the final app size.

App thinning

Apple packages optimized, device-specific versions of your app via app thinning. What your users download only includes code and resources required by their specific device. You can generate an app size report using Xcode or look at the “App Store File Sizes” report in iTunes Connect to see what the actual initial download size of your app will be. Note that these figures represent the maximum amount that your users will download — see the application updates section of this page for more information on how updates are optimized.

CPU architectures

Our framework includes a multi-architecture binary that contains slices for armv7, arm64, i386, and x86_64 CPU architectures. ARM slices are used by physical iOS devices, while i386 and x86_64 are used by Simulator and are stripped from your app during the build and archive process. When a user downloads your app from the App Store, they receive only the architecture that their device requires.


Bitcode is included for ARM architectures but does not affect the final size of your application. Bitcode is an unoptimized intermediate code representation that is used by Apple for potential recompilation and re-optimization of your app binary, after App Store submission. As metadata solely intended for build optimization, bitcode is never downloaded by your users.

If you have disabled bitcode in your project, it is not necessary for you to remove bitcode from frameworks that contain it. Regardless of whether your app takes advantage of bitcode, the version of your app that the App Store delivers to your users never contains bitcode.

Application updates

When you update your application, your users download only the files that have changed in that update. These partial updates are commonly known as “delta updates”. If resources and binaries in your app have not changed, they will not be downloaded again. See Apple’s Reducing Download Size for iOS App Updates guide for more information on how to take advantage of delta updates.

Debug symbols

The Mapbox Maps SDK for iOS framework download includes dSYM and BCSymbolMap files. These are used for crash symbolication and are not included in the app that your users download.

Dynamic versus static frameworks

Following Apple’s platform guidelines, Mapbox recommends using the dynamic-linked version of the SDK in your app. If you have installed the SDK via CocoaPods or Carthage, you are already using the dynamic framework. See Apple’s Overview of Dynamic Libraries for information on how dynamic libraries work and a discussion of their benefits.

Mapbox does additionally build and publish a statically-linked version of the SDK, but we do not recommend it for general use.

Reducing the size of your app

We recommend that you read Apple’s Reducing the size of my App guide to learn about ways to accurately measure and reduce the size of your app.

Was this page helpful?