NUMBERS File Documentation

Summary

A .numbers file is a spreadsheet created with Apple Numbers, the iWork spreadsheet app for Mac, iPhone and iPad. Its MIME type is application/vnd.apple.numbers. The file is a ZIP package whose data is stored as binary IWA (Snappy-compressed Protocol Buffers) streams, so Excel cannot open it directly. On Windows or Linux, open it free in a browser at iCloud.com and export it as .xlsx if you need Excel.

Technical details

FeatureValue
Full nameApple Numbers spreadsheet
File extension.numbers
MIME typeapplication/vnd.apple.numbers
Format typeZIP package of binary IWA streams
Container / base formatZIP archive; inner Index.zip of IWA files
Payload encodingProtocol Buffers, Snappy-compressed (IWA)
DeveloperApple Inc.
Introduced2007 (Numbers 1.0, iWork ’08)
Current format sinceNumbers 3.0 (2013), IWA-based
Open standardNo — proprietary, undocumented
Magic number (hex)50 4B 03 04 (ZIP PK\x03\x04) at offset 0
Identifying entriesIndex/*.iwa inside the package
Package (bundle) formOn macOS may be a folder, not a single file
Macro languageNone (no executable scripting)
PlatformsmacOS, iOS/iPadOS, Numbers for iCloud (web)
No native app onWindows, Android, Linux
Export targetsXLSX, CSV, PDF (via Numbers / iCloud)
Third-party readerLibreOffice (libetonyek), numbers-parser
Related extensions.pages, .key, .xlsx, .csv, .ods
SpecificationProprietary; support.apple.com/numbers
File signature (magic bytes)
50 4B 03 04

Offset 0, 4 bytes: P K \x03 \x04, the local file header of a ZIP archive, because a single-file .numbers document is a ZIP package. The signature is shared with every ZIP and with XLSX, so it does not identify Numbers on its own. What marks a Numbers document is the internal layout: an Index/ directory (or an inner Index.zip) of .iwa files — Snappy-compressed Protocol Buffers — alongside a Metadata/ folder and preview.jpg. Note that on macOS the same document is sometimes saved as a folder bundle rather than one file, which has no signature at all; that is why an e-mailed .numbers occasionally arrives looking like a ZIP or a folder.

What is a .numbers file?

A .numbers file is the native document of Apple Numbers, the spreadsheet application in Apple’s iWork suite, introduced in 2007 with iWork ’08. Numbers is free on every Mac, iPhone and iPad and also runs as a web app at iCloud.com. Unlike Excel’s single endless grid, a Numbers sheet is a freeform canvas that can hold several independent tables, charts, text boxes and images side by side — a design difference that matters when the file is converted to Excel, because each Numbers table becomes a separate object. Its MIME type is application/vnd.apple.numbers.

Since Numbers 3.0 (2013) the document is a ZIP package whose spreadsheet data is stored in binary IWA files: Snappy-compressed Protocol Buffers streams. The format is proprietary and undocumented by Apple, so everything known about its internals comes from reverse engineering. There is no Numbers application for Windows, Android or Linux; Apple’s supported cross-platform route is Numbers for iCloud in a browser, which can view, edit and export the file, including a download as Excel, PDF or CSV using Apple’s own conversion engine.

The package layout: Index, Metadata and Data

Unzip a modern single-file .numbers and it is not XML like ODS or XLSX; it is a set of binary streams and a few support files.

document.numbers  (ZIP)
 ├─ Index/                 the actual document, as .iwa streams
 │   ├─ Document.iwa
 │   ├─ CalculationEngine.iwa
 │   ├─ Tables/ ... .iwa
 │   └─ ...
 ├─ Metadata/
 │   ├─ DocumentIdentifier
 │   └─ BuildVersionHistory.plist   app + version that wrote it
 ├─ Data/                  embedded media (images, attachments)
 ├─ preview.jpg            Quick Look thumbnail of the first sheet
 └─ preview-micro.jpg

The real content lives under Index/ as .iwa files. Metadata/ holds a document identifier and a BuildVersionHistory.plist recording which Numbers versions touched the file, which is how Numbers decides whether an old document needs migrating. In some iWork versions the Index/ streams are themselves collected into an inner Index.zip, so that saving a document only has to lock one file rather than coordinate writes to many individual .iwa streams. On macOS the same document may instead be a folder package rather than a single ZIP, which is why a file transferred by mail or cloud sync sometimes arrives as a folder or a raw ZIP and looks corrupted when it is not.

IWA: the Snappy framing Apple bends

Each .iwa file is a Snappy-compressed stream, but Apple does not follow the Snappy framing spec exactly. The stream is a run of chunks, each with a 4-byte header: the first byte is the chunk type (always 0x00 in iWork, meaning a compressed chunk) and the next three bytes are a 24-bit little-endian length of the compressed block that follows.

IWA chunk header (4 bytes):
  byte 0      : 0x00        chunk type (compressed)
  bytes 1-3   : uint24 LE   length of the compressed data
  bytes 4..   : Snappy-compressed block

Two deviations from standard Snappy framing matter to anyone parsing these files: iWork omits the required Stream Identifier chunk at the start, and its compressed chunks carry no CRC-32C checksum. A decoder therefore cannot rely on a generic Snappy framing library; it must read the 4-byte headers itself, decompress each block, and concatenate the results to recover the raw Protocol Buffers stream. This is exactly what reverse-engineered libraries such as LibreOffice’s libetonyek and the Python numbers-parser do.

Protocol Buffers: the object stream inside IWA

Once decompressed, an IWA file is a sequence of serialised Protocol Buffers messages, not a document tree. iWork models a spreadsheet as a graph of numbered objects, and the IWA stores those objects one after another. Each object is preceded by a varint giving the length of an ArchiveInfo message; that message carries the object’s unique identifier and the message type, and is followed by the object’s own payload.

<varint length> ArchiveInfo { identifier; message_info[] }
<object payload: a typed protobuf message>
<varint length> ArchiveInfo { ... }
<object payload>
...

Objects reference each other by identifier, so a table cell points to a style object, a formula object, a shared-string table and so on, rather than embedding them. Reconstructing the visible spreadsheet means decoding every message, resolving those cross-references, and walking from the top-level document object down to the tables and their cells. Because the .proto schemas are Apple’s and unpublished, third-party readers infer field meanings from observed data, which is why their import fidelity is good for values but imperfect for layout, and why they lag behind the newest Numbers versions when Apple changes the schema.

Opening a .numbers file without a Mac

Because the format is proprietary and there is no Numbers app off Apple platforms, the practical answer on Windows, Linux or Android is Numbers for iCloud: sign in at iCloud.com with a free Apple Account, upload the file into the browser, and view or edit it. From there, Download a Copy exports the sheet as Excel, PDF or CSV using Apple’s own engine, which preserves formulas and formatting far better than any third-party converter because it is the same code that wrote the file. An offline fallback is LibreOffice Calc, whose libetonyek import filter reads .numbers directly; treat that as data recovery rather than faithful rendering, since formatting varies and the newest documents may not parse.

Microsoft Excel has no import filter for the format, so “open a .numbers in Excel” is not possible without converting first. The conversion caveat is structural: Numbers allows several tables on one sheet, and each becomes a separate table or sheet in Excel, so a multi-table canvas does not map to Excel’s one-grid-per-sheet model cell-for-cell.

References