Implementation:Puppeteer Puppeteer FileUtil

Property	Value
sources	packages/browsers/src/fileUtil.ts
domains	Archive Extraction, File System Operations
last_updated	2026-02-12 00:00 GMT

Overview

Description

The FileUtil module provides archive extraction utilities for the @puppeteer/browsers package. It handles unpacking downloaded browser archives in multiple formats across different operating systems. The module supports five archive formats:

• ZIP -- Extracted using the extract-zip library (cross-platform)
• tar.bz2 -- Extracted using the system bzip2 utility piped through tar-fs
• tar.xz -- Extracted using the system xz utility piped through tar-fs (Firefox 135+)
• DMG -- macOS disk images mounted via hdiutil and copied with cp -R
• EXE -- Windows Firefox installers extracted via /ExtractDir flag

The module uses Node.js streams and child processes to perform extraction efficiently. For tar-based formats, it creates a transform stream that pipes data through the decompression utility and then through tar-fs for extraction. DMG handling involves mounting the disk image, locating the .app bundle, copying it to the destination, and unmounting.

Usage

This module is used internally during browser installation after the archive has been downloaded. The unpackArchive function is the primary entry point, automatically selecting the correct extraction strategy based on the file extension.

Code Reference

Source Location

packages/browsers/src/fileUtil.ts

Signature

export async function unpackArchive(
  archivePath: string,
  folderPath: string,
): Promise<void>;

export const internalConstantsForTesting: {
  xz: string;
  bzip2: string;
};

Import

import {unpackArchive} from './fileUtil.js';

I/O Contract

Inputs

Parameter	Type	Description
archivePath	string	Absolute or relative path to the downloaded archive file
folderPath	string	Destination directory for extracted contents; resolved to absolute if relative

Outputs

Return	Type	Description
result	Promise<void>	Resolves when extraction completes; rejects with error details if extraction fails

Supported Archive Formats

Extension	Extraction Method	Platform
.zip	extract-zip library	All platforms
.tar.bz2	bzip2 -d piped to tar-fs	Linux, macOS
.tar.xz	xz -d piped to tar-fs	Linux, macOS
.dmg	hdiutil attach + cp -R	macOS only
.exe	Spawned with /ExtractDir flag	Windows only (Firefox)

Usage Examples

import {unpackArchive} from './fileUtil.js';

// Extract a ZIP archive (Chrome on any platform)
await unpackArchive(
  '/tmp/chrome-linux64.zip',
  '/home/user/.cache/puppeteer/chrome/131.0.6778.109'
);

// Extract a tar.xz archive (Firefox 135+ on Linux)
await unpackArchive(
  '/tmp/firefox-135.0a1.en-US.linux-x86_64.tar.xz',
  '/home/user/.cache/puppeteer/firefox/nightly_135.0a1'
);

// Extract a DMG (Firefox on macOS)
await unpackArchive(
  '/tmp/firefox-135.0a1.en-US.mac.dmg',
  '/Users/user/.cache/puppeteer/firefox/nightly_135.0a1'
);

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime