IWA Files

What is a .IWA file?

The full term IWA stands for “Apple iWork Archive.” This is an internal binary format that Apple has used on pages, Numbers, and Keynote files of recent iWork applications (which Apple released in 2013) documents. The format is made by Apple for usage in the updated versions of macOS/iOS and iCloud-based iWork. Unlike previous, heavily using .xml inside iWork ’09 version, these files usually contain the IWA format inside of document package. Users should open either their .pages, .numbers, or .key files in the unpacked folders (they usually can be found at the Index/) or in the form of decompressed files of .pages, numbers, and key file types.

The data are stored in form of serialized record streams where each object such as text, styles, table, chart, slide /page structure, objects, references etc., is represented inside of a document. Note, however, that even Apple’s naming of this format with “Archive” does not mean that a certain kind of .zip files should be expected here. Indeed it is an embedded binary inside of the iWork package. No any other format uses .iwa file extension as the primary one. So, in case your file appears from Apple document and is placed with Metadata / Preview/Index/*.iwa files - it is an archive component of some iWork. Do not try opening .iwa file! Open your document file (.pages, .numbers, or .key).

How to open a .IWA file

Technical details

The IWA format is a binary format as opposed to plain text. Payload comprises Protocol Buffers messages grouped into blocks, which are later on compressed with Snappy-style algorithms and encoded with Apple-defined object schema. The content text is serialized to Unicode strings embedded into protocol buffer fields. The file, though, does not get into a human-readable shape, due to inclusion of binary framing, object referencing, and groups compression.

IWA documents do not have an existing public Apple's MIME type nor a registered magic number. Generic file-identification applications will usually guess the file type to be application/octet-stream or a generic category, such as data, since there's no reliable Apple-defined file identification for this format. Isolated files are not ZIP packages, as it could be supposed, the ZIP file/package itself being a container to a .pages, .numbers, or .key document, where .iwa files are embedded into.

Modern versions of packages contain several IWA files typically residing at /Index. Document.iwa, CalculationEngine.iwa, AnnotationAuthorStorage.iwa, Table-XXX are some typical IWA stream names, though more advanced document streams can also be stored in /Index/Tables subdirectory. IWA document stream format is built as an alternating set of length-delimited record groups containing various objects IDs, other references between those objects, typed fields as well as content parts such as document-component texts, styles and tables.

Unfortunately, there are no published specifications or schema descriptions from Apple for these documents structures, and their third-party parsing becomes possible thanks to some reverse engineering work and dedicated libraries like libetonyek. This implies certain backward-compatibility issues related to particular generation of iWork programs: newer version may have fields understood only by this version which older iWork parser does not know about.

The IWA streams differ greatly in size. Some metadata streams might have size of several kilobytes. More advanced streams may require megabytes in size. Usually large video/image documents are stored in dedicated package resources rather than in IWA format files themselves.

How to convert .IWA files

The .pages, .numbers, or .key package in full is what matters in terms of conversions here. Documents from iWork applications nowadays come as a bunch of different Index/*.iwa streams, so extracting them will only be good for recovery operations. You still won't have the opportunity to work with either XML or plaintext.

Concerning Pages: possible export formats are .PDF in case one wants to keep format but share with others without editing, .DOCX if one wants to use the document in Word, and .EPUB and plaintext as options which don't require keeping formatting information. In such documents formatting remains the same because the app supports Pages' layouts, linked text boxes, comments, fonts and effects. For Pages you use File > Export To > PDF or Word on the document's package.

Export for Numbers means getting XLSX in Excel and CSV and TSV for data transfer. As to Keynote it can provide PPTX for PowerPoint, PDF as printout, sequence of images for presentation pages or movie format in case one needs time-based animations in the slides. Such conversion is usually more complete concerning original effects then others.

Conversion for the supported Packages in the batch mode is possible via command lines like this in LibreOffice: LibreOffice --convert-to pdf --outdir <directory> document.pages (for document.pages of course). Some information might be lost in linked textboxes, freeform tables, multiple ones in the sheets; some parts of Keynote's effects may remain too.

Common problems and fixes

For example, a common mistake is double-clicking Index/Document.iwa and getting the message “There is no application set to open the document.” This document.iwa is just one single stream inside a Pages, Numbers or Keynote package. Open the corresponding package file (.pages/.numbers/.key) in Pages version 5.0+ (respectively), Numbers 3.0+, or Keynote 6.0+, or on iCloud Pages/Numbers/Keynote. If Apple states that some document cannot be open (damaged), make sure that your transferring kept an entire ZIP package/macosx package and includes the whole Index/ Directory as well as media files and try downloading it again from iCloud or any other origin source because partial copying results in leaving just a few Document.iwa streams.

If you receive a shared iWork document as a directory, then, indeed, your macOS reveals package contents already, so zip it all and send back or alternatively just export the document from Apple iWork as a PDF or DOCX, or Numbers/XLSX or Keynote/PPTX files. Collabora or even libreoffice can produce errors importing such document and/or will show only empty pages/lines/tables due to the unknown fields in it, which is used by newer iWork. Anyway, if you see some problems during importing/exporting, please update Collabora/Libreoffice first and try exporting via Apple again, as a safer alternative test. Fonts that you do not have or that could not apply correctly will shift the layout while exporting/importing. Also, broken reference to images/videos shows that just Index/*.iwa has been transferred without proper Data/ directory as media files. For the files without correct extension - test zip content itself first before renaming. Of course, the encrypted or policy-limited iWork document cannot be opened from someone else’s account.

Security considerations

This .iwa stream by itself is not a program file and lacks a standard macro mechanism that Microsoft Office programs such as VBA have. The major threat here lies in the parsing vulnerabilities of the apps which process invalid iWork format; consequently, make sure Apple Pages, Numbers, and Keynote, as well as LibreOffice and Collabora Office, are always updated. Unusual .pages, .numbers, or .key files are dangerous as they might come through your email or chatting application and should only be opened with an untrusted viewer or via an online file reader, whenever possible. The top level package might include images, videos, music files, fonts, thumbs, comments sections, statistics on documents usage, history of authorship, and other meta content about the document's creation. Metadata regarding privacy might be stored within comments, history of any changed or deleted sections, notes sections of the workbook or slideshow, or in previously linked resources. When uploading to website, save it first in PDF without additional meta data and without notes sections; also check the hidden sheets/slides.

History and versions

Modern versions of the Apple format called iWork appeared in 2013 and include software packages Pages 5.0, Numbers 3.0 and Keynote 6.0 with a different set of documents. They superseded the old iWork '09 format. The previous version of iWork featured other internal document files and used such XML formats as index.xml.gz rather than Snappy-compressed protobuf-based streams .iwa. The new format helped reach equal functionality among all document formats of macOS, iOS and web apps within iCloud. Although in 2013 there appeared much complaints concerning the deletion of features of previous iWork '09 package in its newer version, after several updates most of them came back to Pages, Numbers and Keynote programs with .iwa format.

This format was not standardized in any way by ISO organization, ECMA organization, or OASIS, IETF. Being peculiar to only Apple corporation, .iwa format could be easily deciphered by third party thanks to Document Liberation Project, which includes software like libetonyek used by LibreOffice and related applications to read iWork document format. Contemporary versions of Apple's office products still use document streams in .iwa format.

Related formats

The iWork document files for end users are saved with extensions .pages, .numbers, and .key and consist of packages. These packages normally contain the .iwa streams and preview, metadata, and media resources. The .iwa stream is merely a representation of internal binary record that doesn’t qualify as ZIP archive itself although the current office files often use ZIP as wrapper. As for sharing files, the .docx, .xlsx, and .pptx are Office Open XML ZIP packages and therefore they are more convenient to exchange between editors compared to the Apple’s propriety protobuf formats. The .odt, .ods, and .odp files are the open OpenDocument formats by LibreOffice and other similar software products and thus they are preferable if it comes to vendor-independent editing of documents rather than iWork internals. The .pdf format is the one to use for distribution of the files. The .rtf and .txt file formats save only plain text of Pages exports, and .csv and .tsv can store only the data of the spreadsheet but not the formulas, charts, styles, and comments.