PKG File Documentation

Summary

A Mac OS X Installer Package is the file macOS uses to install software. A modern flat .pkg is an xar archive that bundles the files to install, a Bill of Materials listing every path, an XML manifest, and optional install scripts. Its MIME type is application/x-xar. Double-clicking one opens Apple’s Installer, which can request an admin password and run those scripts, so a .pkg is more privileged than an app you drag into Applications.

Technical details

FeatureValue
Full nameMac OS X Installer Package
File extension.pkg
MIME typeapplication/x-xar
Format typeInstaller package, binary
Container / base formatxar archive (flat package)
DeveloperApple
IntroducedFlat XAR-based .pkg since Mac OS X 10.5 Leopard (2007); bundle .pkg since Mac OS X 10.0
Installer appInstaller.app; command line installer(8)
Payloadgzip- (or bzip2-) compressed cpio archive of the files to install
Bill of MaterialsBom file listing every path, size and permission
ManifestPackageInfo / Distribution XML (identifier, version, target)
ScriptsOptional preinstall / postinstall, run with installer privileges
Byte orderBig-endian (xar header fields)
Magic number (hex)78 61 72 21 (“xar!”)
SigningApple code signing and notarization; enforced by Gatekeeper
Open standardPartial — xar is open source; package layout is Apple-defined
Related extensions.mpkg, .dmg, .xip, .app
Specificationgithub.com/apple-oss-distributions/xar
File signature (magic bytes)
78 61 72 21

Offset 0, 4 bytes. In ASCII these read xar!, the magic number of a xar archive, which is the container for a modern “flat” macOS installer package. The four magic bytes are followed by a 2-byte header size and a 2-byte format version, all big-endian. Older macOS packages are bundles (folders) rather than single files, so they have no signature of their own.

What is a PKG file?

A .pkg is a Mac OS X Installer Package, the file macOS uses to install software. When an application is not simply dragged into the Applications folder, it ships as a .pkg that Apple’s Installer runs to copy files into place, set permissions, and execute any setup steps the software needs. Apple has used the .pkg extension for this role since the earliest Mac OS X releases (and NeXTSTEP before that), but the internal format changed. Since Mac OS X 10.5 Leopard (2007), the modern “flat” package is a single xar archive file; older packages were bundles, ordinary folders that macOS presented as one installer.

Because a package can run scripts with administrator privileges, a .pkg is more powerful, and more security-sensitive, than an app you drag to Applications. The sections below describe the four things a flat package actually contains, the xar container that holds them, and the script and signing mechanics that make the format both useful and worth treating carefully. Note that the .pkg extension is also used by unrelated formats (PlayStation console packages, old Symbian install scripts); this page is about the macOS installer.

The xar container: header, table of contents, heap

A modern flat package is an xar (eXtensible ARchive) file. Every xar begins with a short binary header, all fields big-endian, whose first four bytes are the ASCII magic xar! (78 61 72 21, the 32-bit value 0x78617221).

Offset  Size  Field
0       4     Magic: 'xar!' (0x78617221)
4       2     Header size (bytes)
6       2     Version (currently 1)
8       8     TOC length, compressed
16      8     TOC length, uncompressed
24      4     Checksum algorithm (0 none, 1 SHA-1, 2 MD5, 3 SHA-256, 4 SHA-512)

After the header comes the table of contents, a zlib-compressed XML document that describes every entry in the archive: its name, type, offset into the data area, compressed and uncompressed sizes, and checksums. Because the TOC is XML, a xar is self-describing and extensible: a reader can list the whole archive without decompressing the payload. Following the TOC is the heap, the concatenated, individually compressed file data that the TOC points into. This three-part layout (header, TOC, heap) is what lets extractors such as xar on the command line, or 7-Zip on Windows, pull files out of a .pkg without any macOS involvement.

Inside a package: payload, Bill of Materials, manifest, scripts

The xar archive of an installer package holds four kinds of entry, and understanding them explains exactly what happens when you run the file.

Component.pkg (xar)
 ├─ Payload          gzip-compressed cpio archive of the files to install
 ├─ Bom              binary Bill of Materials: every path, size, mode, owner
 ├─ PackageInfo      XML: identifier, version, install target, script refs
 └─ Scripts          gzip-cpio of preinstall / postinstall shell scripts

The Payload is the actual software, stored as a cpio archive that is then gzip-compressed; unpacking it reproduces the directory tree the package installs. The Bill of Materials (the Bom file) is a binary index listing every file the package will lay down, with its path, size, permission bits and owner, so the installer knows precisely what it is placing and can later verify or remove it. The PackageInfo XML is the manifest: it carries the package’s reverse-DNS identifier, its version, the install location (the target volume and relative path), and references to any scripts. The optional Scripts entry holds preinstall and postinstall shell scripts.

A distribution package (also seen as .mpkg) adds a top-level Distribution XML that can present a choices UI and bundle several component packages behind one installer. That is how a single download can offer optional components and install several sub-packages in sequence.

Install scripts and elevated privilege

The reason a .pkg deserves more caution than a drag-install is the Scripts entry. The preinstall script runs before the payload is written and the postinstall script runs after, and both execute with the privileges the installation is granted, which for a system-level install means root. That is legitimately useful: a package might stop a running service, register a launch daemon, or migrate old settings. It is also the vector by which malware and adware have shipped as .pkg files, because “install this app” can quietly mean “run this script as root.”

Running a package on the command line makes the mechanism explicit: sudo installer -pkg file.pkg -target / installs to the root volume, and the sudo is what the scripts inherit. This is why inspecting an untrusted package before running it is worthwhile: a viewer that reads the xar can show the preinstall and postinstall scripts as plain text so you can see what they do, without executing anything.

Signing, notarization and Gatekeeper

A xar archive supports an embedded signature, and Apple uses it to sign and notarize legitimate installer packages. The signature covers the table of contents (and therefore, through the TOC’s per-file checksums, the payload), so tampering with any file in the archive invalidates it. When you open a downloaded .pkg, macOS Gatekeeper checks that signature and the notarization ticket before letting Installer proceed. An unsigned or non-notarized package triggers the “from an unidentified developer” warning, and a package whose contents no longer match its signature is reported as “damaged.”

These checks are advisory rather than absolute: a user can still override Gatekeeper in System Settings for a package they trust. The signature guarantees integrity and identity, not safety, so a signed package from a dubious source is still worth inspecting.

Reading a package on a system without macOS

Because the container is an open xar archive, a .pkg can be opened for inspection anywhere, even though the software inside can only be installed on macOS. On Windows, 7-Zip recognises the xar! magic and lists the archive; on Linux, xar -xf file.pkg extracts the entries, after which the Payload is a gzip stream wrapping a cpio archive that gunzip and cpio unpack. This is how you read a package’s contents, or pull a single bundled app out of it, without running Apple’s Installer at all. What you cannot do off macOS is install: the Bill of Materials, the target paths and the scripts assume a macOS filesystem and privilege model.

The .pkg is one of several macOS delivery formats. A DMG disk image is a mountable volume you usually drag from, not an installer, and a .xip is a signed archive Apple uses for very large downloads like Xcode. The package is the one that actively runs an installation.

Frequently asked questions

Why can a PKG do more than dragging an app to Applications?

A drag-install just copies a self-contained .app bundle. A package can lay down files anywhere on the target volume via its Bill of Materials and, crucially, run preinstall and postinstall scripts with the installer’s privileges. That extra capability is what installers need for services and system components, and also what makes an untrusted package worth inspecting first.

How can I see what a PKG will install before running it?

Open the xar and read its entries. A free inspector on macOS shows every file in the Payload, the Bill of Materials, the install scripts and the signer; on any OS, extracting the archive with 7-Zip or the xar tool lets you read the PackageInfo XML and the preinstall/postinstall scripts as plain text.

Why does macOS say a package is “damaged”?

That message usually comes from Gatekeeper, not from actual corruption. It means the package is unsigned or not notarized, or that its contents no longer match its embedded signature. Re-download from the official source; only override the warning if you fully trust the origin.

References