pkg unpacker

Unpack any pkg application.

Keep in mind that this tool doesn't give you the full source code if the application was compiled into V8 bytecode. See How it works.

Table of Contents

• Support
• Installation
• Usage
  • As a command line interface
  • As a library
• Features
• How it works
• Credits
• Copyright

Support

As of this writing, pkg-unpacker supports the following tools:

Tool	Supported	Versions	Comment
vercel/pkg	✅	5.0.0 - 5.8.1	N/A
yao-pkg/pkg	✅	5.0.0 - 6.3.2	Does not include experimental support for Node SEA .
AngaBlue/exe	❌	-	N/A

Installation

1. Install Node.js.
2. Download or clone the project.
3. Navigate to the project directory.
4. Install the dependencies:

   npm install

5. Build the project:

   npm run build

Usage

As a command line interface

To start the application, run:

npm start

Here’s an overview of the help command output:

Usage: pkg-unpacker [options]

Options:
  -i, --input <file>     Specify the input binary file path
  -o, --output <folder>  Specify the output folder path (default: ".")
  --run                  Run the unpacked binary (default: false)
  -h, --help             display help for command

Examples:

• Unpack a UNIX application:

$ npm start -i ./pkg_app -o ./unpacked

• Unpack a Windows application:

$ npm start -i ./pkg_app.exe -o ./unpacked

• Unpack a UNIX application and run it:

$ npm start -i ./pkg_app -o ./unpacked --run

As a library

The main logic of pkg unpacker lies in the Unpacker class.

Examples:

• Unpack a UNIX application:

import Unpacker from "./src/unpacker.ts";

const main = async () => {
    const unpacker = await Unpacker.create("./pkg_app");
    await unpacker.unpack("./unpacked");
};

main();

• Unpack a Windows application and run it:

import Unpacker from "./src/unpacker.ts";

const main = async () => {
    const unpacker = await Unpacker.create("./pkg_app.exe");
    await unpacker.unpack("./unpacked", true);
};

main();

Features

• Detects compression formats (Gzip, Brotli)
• Supports code evaluation
• Handles symlinks
• Extracts binaries from all operating systems

How it works

This application does not decompile code. By default, pkg compiles JavaScript into V8 bytecode. Extracted files will remain in this format, except for assets.

Code evaluation works best with small applications as dependencies might be broken.

pkg stores metadata about file names, paths, offsets, lengths, and compression at the end of each binary. This application analyzes those fields to extract and decompress (if necessary) all embedded files.

Examples:

// UNIX app

{"/snapshot/pkg/index.js":{"0":[0,568],"3":[568,118]},"/snapshot/pkg":{"2":[686,12],"3":[698,117]},"/snapshot":{"2":[815,7],"3":[822,117]}} // virtual file system
,
"/snapshot/pkg/index.js" // entrypoint
,
{} // symlinks
,
{} // files dictionnary
,
0 // 0: no compression, 1: Gzip, 2: Brotli

// Windows app

{"C:\\snapshot\\pkg\\index.js":{"0":[0,568],"3":[568,118]},"C:\\snapshot\\pkg":{"2":[686,12],"3":[698,117]},"C:\\snapshot":{"2":[815,7],"3":[822,117]}} // virtual file system
,
"C:\\snapshot\\pkg\\index.js" // entrypoint
,
{} // symlinks
,
{} // files dictionnary
,
0 // 0: no compression, 1: Gzip, 2: Brotli

Credits

pkg

Copyright

See the license.