Tech Note: Expansion File Support for Gear VR (Beta)

Oculus Developer Blog
Posted by Dmitry Soshnikov
August 22, 2017

The recent release of SD Card support for Gear VR makes it easier for more people to experience more VR apps without impacting their local storage size. Carrying on with that theme, today we announce beta support for large expansion files (sometimes referred to as “obb” files) for Gear VR applications. With expansion file support, you can now experiment with shipping applications of up to 5 GB in size by splitting the APK and data files into separate files.

The improvements provided with expansion file support include:

  • A 10X increase over our previous file size restriction. Gear VR applications can now be up to 5 GB (via a 1 GB APK and 4 GB data file).
  • Simplified install requirements. Android applications sometimes require a large amount of free space to complete an install – up to three times the size of the APK itself. This may cause friction for users who experience install failures even though they appear to have enough free space on their device. By moving data to an external file, the total disk space required to complete an install is reduced because the APK file itself becomes smaller.

Using Expansion Files

Expansion files are automatically downloaded and installed when a user installs a Gear VR application. The install process does not complete, and the app is not available for launch, until the expansion file has been completely downloaded. Updates to expansion files are also automatically delivered. If an expansion file is missing the user will be warned the next time they launch the application. We strongly recommend that your app verify the existence and validity of your expansion file at launch, and warn the user if that check fails.

Expansion files are installed into the /sdcard/Android/obb/<package name> folder, and can have any file name at upload. The resulting file will be renamed to the following format:


Applications should look for the file at that path during startup.

Unity and Unreal have existing support for expansion files, which you can leverage with our system. See the respective documentation here:

    1. Unity Engine
    2. Unreal Engine

Note that Unity's “Split Application Binary” option will only generate an expansion file up to 2 GB. For larger applications, you may want to use an asset bundle.

Uploading Expansion Files

Expansion files must be uploaded through our CLI tool using the “—obb” command argument. Here's an example of uploading an apk with an expansion file attached.

./ovr-platform-util upload-gear-build \
--app <app-ID> \
--secret <app-secret> \
--channel alpha \
--apk <path-to-APK> \
--obb <path-to-OBB>

A Note about Beta

Expansion file support is available now in beta form. We encourage you to experiment with it using Release Channels before pushing expansion files to live users. As always, we'd love to hear your feedback.