OBB File Documentation

Summary

An OBB (Opaque Binary Blob) file, officially an Android APK Expansion File, holds the large assets — textures, audio, video, levels — that a game or app ships separately from its .apk. Google introduced it in 2012 to get past the Play Store’s early 50 MB APK limit. Its MIME type is application/octet-stream. You do not open a .obb; you place it at Android/obb/<package.name>/ so the app can find and read it.

Technical details

FeatureValue
Full nameAndroid Opaque Binary Blob (APK Expansion File)
File extension.obb
MIME typeapplication/octet-stream
Format typeApp/game expansion data container; internal layout is developer-defined
CategoryGame files
DeveloperGoogle (Android Open Source Project)
Introduced2012 (Android APK Expansion Files)
Naming convention[main|patch].<version>.<package_name>.obb
Target location/Android/obb/<package_name>/ on shared storage
Size limit2 GB per file; one main plus one optional patch OBB
Open standardPartial — the jobb container and mount API are documented; contents are opaque by design
Common internal layoutZIP archive of assets, a jobb/EncFS filesystem image, or an engine-specific container (Unity, Unreal)
EncryptionOptional (AES via the jobb tool); many OBBs are unencrypted
Magic numberNone guaranteed. ZIP-based OBBs start 50 4B 03 04 (PK\x03\x04); encrypted/engine containers have no readable header
Mounted byAndroid StorageManager.mountObb() (API 9+)
Related extensions.apk, .aab, .xapk, .apks
SpecificationAndroid Developers — APK Expansion Files
Is this OBB a ZIP? Check the first bytes

An OBB has no guaranteed signature, because “opaque” means the developer chooses the internal layout. Many are plain ZIP archives, recognisable by 50 4B 03 04 (PK\x03\x04) at offset 0; rename such a file to .zip or open it with 7-Zip or ZArchiver to inspect the assets. Files built with Google’s jobb tool are a mountable EncFS-style filesystem image, and encrypted OBBs (or Unity/Unreal engine containers) have no readable header at all. If the first bytes are not PK, treat the file as opaque: place it, do not extract it.

What is an OBB file?

OBB stands for Opaque Binary Blob, and its official name in the Android platform is an APK Expansion File. Google introduced it in 2012 as part of the Android Open Source Project. At the time the Google Play Store capped an APK at 50 MB, which was far too small for a modern game full of textures, audio and video. Expansion files let a developer ship that bulk separately: the small .apk holds the code and the manifest, and one or two .obb files hold the heavyweight assets, up to 2 GB each.

The word “opaque” is precise and important. Android makes no assumptions about what is inside an OBB; the internal layout is entirely the developer’s choice. It might be a ZIP archive of assets, a mountable filesystem image produced by Google’s jobb tool, or an engine-specific container written by Unity or Unreal. The platform treats the whole file as a black box, reads it on the app’s behalf, and never tries to interpret its structure. That is why there is no single OBB “format” and no guaranteed magic number.

The filename and folder are the format

For an OBB, the two things that actually matter are its name and its location, not its contents. Android finds expansion data by convention, and if the file is misnamed or in the wrong place, the app cannot see it and either re-downloads it or refuses to start. The filename follows a fixed pattern:

[main|patch].<version>.<package_name>.obb

main.5.com.example.game.obb      ← primary asset file, version 5
patch.5.com.example.game.obb     ← optional smaller update, layered on top

The main OBB carries the bulk of the assets. The optional patch OBB is a smaller file layered over the main one, so a developer can push a content update without re-shipping gigabytes. The <version> is an integer that must match what the app expects, and <package_name> is the app’s exact package ID. The file must sit at:

/Android/obb/<package_name>/main.<version>.<package_name>.obb

on the device’s shared (internal) storage. The folder name under Android/obb/ is the package name, and it must match the app exactly. When you install from Google Play, the store downloads the OBB and places it here automatically. When you sideload, you do this step yourself.

The ZIP-based OBB

The most common internal layout is a plain ZIP archive. Android’s own expansion-file documentation ships a Zip helper library (APEZProvider) precisely because so many developers just zip their assets and read them back with a content provider that indexes the archive. A ZIP-based OBB begins with the local file header signature 50 4B 03 04 (the ASCII PK\x03\x04 that opens every ZIP), so you can identify it by its first four bytes and open it with any archive tool.

This is the only case where inspecting the contents is straightforward: rename the file to .zip, or open it directly in 7-Zip on the desktop or ZArchiver on the phone, and you can browse the textures, audio and level data inside. What you should not do is extract and repack it: the game reads the blob directly by name, and rebuilding the archive usually changes offsets or breaks the developer’s index, which stops the game working.

The jobb filesystem image and encryption

The other documented layout is produced by jobb, an Android SDK command-line tool that builds an OBB as a mountable filesystem rather than an archive. On the device the app calls StorageManager.mountObb() (available since Android 2.3, API level 9), and the operating system mounts the blob as a read-only volume that the app then reads through ordinary file paths. This gives large games random access to individual assets without unpacking the whole file.

jobb can also encrypt. It takes a package name (-pn), a minimum app version (-pv) and an optional password (-k); with a key it wraps the filesystem in AES encryption keyed to that password, so only the matching app can mount and read it. An encrypted OBB has no readable header and cannot be opened as an archive at all — it is genuinely opaque. The package name and version baked into the OBB by jobb are what the mount call checks, which is another reason the naming has to line up exactly.

jobb flagMeaning
-dInput directory to package (or output directory when extracting)
-oOutput OBB filename
-pnPackage name of the app allowed to mount the file
-pvMinimum app version that may mount the file
-kPassword — encrypts the new OBB, or decrypts an existing one
-ovBuild an overlay (patch) OBB over a previous version

Installing an APK together with its OBB

Sideloading a large game means handling both parts. Install the .apk first, then copy the .obb to Android/obb/<package_name>/, creating that folder if it does not exist, keeping the exact filename and version number. Many downloads bundle the two together as an .xapk or .apks file, which is itself a container holding the APK plus the OBB (and sometimes split APKs). An installer such as Split APKs Installer (SAI) unpacks the bundle, installs the APK and drops the OBB in the right folder automatically. If a game keeps saying “downloading additional data” or will not launch, the OBB is almost always missing, misnamed, or in the wrong package folder.

Frequently asked questions

Where do I put an OBB file?

Copy it to Android/obb/<package_name>/ on internal storage, creating the folder if it is missing, and keep the exact filename (for example main.5.com.example.game.obb). The package-name folder must match the app, or the game will not find its data.

Do I need to extract the OBB file?

No. Place the whole .obb unchanged. The app reads the blob directly, and extracting or renaming its internal files breaks the developer’s index or the mount, which stops the game from loading.

Can I convert an OBB to an APK?

No, they are different things. The OBB holds the game’s data; the APK is the installable app. The game needs both: the APK installed and the OBB placed in Android/obb/. Neither can be turned into the other.

References