How to unpack and pack pkg file?

How to Unpack and Repack macOS .pkg Files

Learn the essential steps to extract, modify, and repack macOS installer (.pkg) files for customization, troubleshooting, or analysis.

macOS installer packages, commonly known as .pkg files, are a convenient way to distribute software. However, there are times when you might need to inspect their contents, modify installation scripts, or even repackage them with custom configurations. This guide will walk you through the process of unpacking and repacking these files using command-line tools available on macOS.

Understanding the .pkg File Structure

A .pkg file is essentially an archive that contains several components. At its core, it's often a XAR (eXtensible ARchiver) archive. Inside, you'll typically find a Payload file (which is a compressed CPIO archive containing the actual application files), a Scripts directory (containing pre- and post-installation scripts), and a PackageInfo file (XML metadata about the package). Understanding this structure is key to successful manipulation.

flowchart TD
    A[macOS .pkg File] --> B{XAR Archive}
    B --> C[PackageInfo (XML Metadata)]
    B --> D[Payload (Compressed CPIO)]
    B --> E[Scripts Directory]
    D --> F[Application Files]
    E --> G[Pre-install Script]
    E --> H[Post-install Script]

Typical structure of a macOS .pkg file

Unpacking a .pkg File

The primary tool for unpacking .pkg files is the xar command-line utility. This tool allows you to extract the contents of the package into a directory, making its components accessible for inspection or modification. Once extracted, you'll need to further decompress the Payload to get to the actual application files.

1. Create a Working Directory

First, create a dedicated directory to store the extracted contents of your .pkg file. This helps keep your workspace organized.

2. Extract the .pkg Archive

Use the xar command to extract the main .pkg file. This will create several files and directories within your working directory, including PackageInfo, Payload, and potentially a Scripts directory.

3. Decompress the Payload

The Payload file is typically a compressed CPIO archive. You'll need to decompress it using zcat (or gunzip) and then extract its contents using cpio into a new directory, often named root or contents.

mkdir my_pkg_work
cd my_pkg_work
xar -xf /path/to/your/installer.pkg
mkdir root
zcat Payload | cpio -i --preserve-modification-times -D root

Commands to unpack a .pkg file and extract its payload

Repacking a .pkg File

After making your desired modifications (e.g., editing scripts, adding/removing files from the root directory), you can repackage the components back into a new .pkg file. This involves reversing the unpacking process: first creating a new Payload from your modified root directory, and then bundling everything back into a XAR archive.

1. Recreate the Payload

Navigate into your root directory and use find and cpio to create a new compressed Payload file. This will contain all your modified application files.

2. Update PackageInfo (Optional)

If you made significant changes, you might need to update the PackageInfo XML file to reflect new sizes or versions. This is often not strictly necessary for simple modifications but is good practice.

3. Re-archive into .pkg

Use the xar command again to bundle the PackageInfo, the newly created Payload, and any Scripts directory back into a new .pkg file. Ensure you specify the correct order and paths.

cd root
find . | cpio -o --format odc --owner 0:80 | gzip -c > ../NewPayload
cd ..
xar --compression none -cf NewInstaller.pkg PackageInfo NewPayload Scripts

Commands to repackage modified contents into a new .pkg file