Skip to main content
Bun provides a fast, native implementation for working with tar archives through Bun.Archive. It supports creating archives from in-memory data, extracting archives to disk, and reading archive contents without extraction.

​
Quickstart

Create an archive from files: 
const archive = Bun.Archive.from({
  "hello.txt": "Hello, World!",
  "data.json": JSON.stringify({ foo: "bar" }),
  "nested/file.txt": "Nested content",
});

// Write to disk
await Bun.Archive.write("bundle.tar", archive);
Extract an archive: 
const tarball = await Bun.file("package.tar.gz").bytes();
const archive = Bun.Archive.from(tarball);
const entryCount = await archive.extract("./output");
console.log(`Extracted ${entryCount} entries`);
Read archive contents without extracting: 
const tarball = await Bun.file("package.tar.gz").bytes();
const archive = Bun.Archive.from(tarball);
const files = await archive.files();

for (const [path, file] of files) {
  console.log(`${path}: ${await file.text()}`);
}

​
Creating Archives

Use Bun.Archive.from() to create an archive from an object where keys are file paths and values are file contents: 
const archive = Bun.Archive.from({
  "README.md": "# My Project",
  "src/index.ts": "console.log('Hello');",
  "package.json": JSON.stringify({ name: "my-project" }),
});
File contents can be:
  • Strings - Text content
  • Blobs - Binary data
  • ArrayBufferViews (e.g., Uint8Array) - Raw bytes
  • ArrayBuffers - Raw binary data
const data = "binary data";
const arrayBuffer = new ArrayBuffer(8);

const archive = Bun.Archive.from({
  "text.txt": "Plain text",
  "blob.bin": new Blob([data]),
  "bytes.bin": new Uint8Array([1, 2, 3, 4]),
  "buffer.bin": arrayBuffer,
});

​
Writing Archives to Disk

Use Bun.Archive.write() to create and write an archive in one operation: 
// Write uncompressed tar
await Bun.Archive.write("output.tar", {
  "file1.txt": "content1",
  "file2.txt": "content2",
});

// Write gzipped tar
const files = { "src/index.ts": "console.log('Hello');" };
await Bun.Archive.write("output.tar.gz", files, "gzip");

​
Getting Archive Bytes

Get the archive data as bytes or a Blob: 
const files = { "hello.txt": "Hello, World!" };
const archive = Bun.Archive.from(files);

// As Uint8Array
const bytes = await archive.bytes();

// As Blob
const blob = await archive.blob();

// With gzip compression
const gzippedBytes = await archive.bytes("gzip");
const gzippedBlob = await archive.blob("gzip");

​
Extracting Archives

​
From Existing Archive Data

Create an archive from existing tar/tar.gz data: 
// From a file
const tarball = await Bun.file("package.tar.gz").bytes();
const archiveFromFile = Bun.Archive.from(tarball);

// From a fetch response
const response = await fetch("https://example.com/archive.tar.gz");
const archiveFromFetch = Bun.Archive.from(await response.blob());

​
Extracting to Disk

Use .extract() to write all files to a directory: 
const tarball = await Bun.file("package.tar.gz").bytes();
const archive = Bun.Archive.from(tarball);
const count = await archive.extract("./extracted");
console.log(`Extracted ${count} entries`);
The target directory is created automatically if it doesn’t exist. Existing files are overwritten. The returned count includes files, directories, and symlinks (on POSIX systems). Note: On Windows, symbolic links in archives are always skipped during extraction. Bun does not attempt to create them regardless of privilege level. On Linux and macOS, symlinks are extracted normally. Security note: Bun.Archive validates paths during extraction, rejecting absolute paths (POSIX /, Windows drive letters like C:\ or C:/, and UNC paths like \\server\share). Path traversal components (..) are normalized away (e.g., dir/sub/../file becomes dir/file) to prevent directory escape attacks.

​
Filtering Extracted Files

Use glob patterns to extract only specific files. Patterns are matched against archive entry paths normalized to use forward slashes (/). Positive patterns specify what to include, and negative patterns (prefixed with !) specify what to exclude. Negative patterns are applied after positive patterns, so using only negative patterns will match nothing (you must include a positive pattern like ** first): 
const tarball = await Bun.file("package.tar.gz").bytes();
const archive = Bun.Archive.from(tarball);

// Extract only TypeScript files
const tsCount = await archive.extract("./extracted", { glob: "**/*.ts" });

// Extract files from multiple directories
const multiCount = await archive.extract("./extracted", {
  glob: ["src/**", "lib/**"],
});
Use negative patterns (prefixed with !) to exclude files. When mixing positive and negative patterns, entries must match at least one positive pattern and not match any negative pattern: 
// Extract everything except node_modules
const distCount = await archive.extract("./extracted", {
  glob: ["**", "!node_modules/**"],
});

// Extract source files but exclude tests
const srcCount = await archive.extract("./extracted", {
  glob: ["src/**", "!**/*.test.ts", "!**/__tests__/**"],
});

​
Reading Archive Contents

​
Get All Files

Use .files() to get archive contents as a Map of File objects without extracting to disk. Unlike extract() which processes all entry types, files() returns only regular files (no directories): 
const tarball = await Bun.file("package.tar.gz").bytes();
const archive = Bun.Archive.from(tarball);
const files = await archive.files();

for (const [path, file] of files) {
  console.log(`${path}: ${file.size} bytes`);
  console.log(await file.text());
}
Each File object includes:
  • name - The file path within the archive (always uses forward slashes / as separators)
  • size - File size in bytes
  • lastModified - Modification timestamp
  • Standard Blob methods: text(), arrayBuffer(), stream(), etc.
Note: files() loads file contents into memory. For large archives, consider using extract() to write directly to disk instead.

​
Error Handling

Archive operations can fail due to corrupted data, I/O errors, or invalid paths. Use try/catch to handle these cases: 
try {
  const tarball = await Bun.file("package.tar.gz").bytes();
  const archive = Bun.Archive.from(tarball);
  const count = await archive.extract("./output");
  console.log(`Extracted ${count} entries`);
} catch (e: unknown) {
  if (e instanceof Error) {
    const error = e as Error & { code?: string };
    if (error.code === "EACCES") {
      console.error("Permission denied");
    } else if (error.code === "ENOSPC") {
      console.error("Disk full");
    } else {
      console.error("Archive error:", error.message);
    }
  } else {
    console.error("Archive error:", String(e));
  }
}
Common error scenarios:
  • Corrupted/truncated archives - Archive.from() loads the archive data; errors may be deferred until read/extract operations
  • Permission denied - extract() throws if the target directory is not writable
  • Disk full - extract() throws if there’s insufficient space
  • Invalid paths - Operations throw for malformed file paths
The count returned by extract() includes all successfully written entries (files, directories, and symlinks on POSIX systems). Security note: Bun.Archive automatically validates paths during extraction. Absolute paths (POSIX /, Windows drive letters, UNC paths) and unsafe symlink targets are rejected. Path traversal components (..) are normalized away to prevent directory escape. For additional security with untrusted archives, you can enumerate and validate paths before extraction: 
const archive = Bun.Archive.from(untrustedData);
const files = await archive.files();

// Optional: Custom validation for additional checks
for (const [path] of files) {
  // Example: Reject hidden files
  if (path.startsWith(".") || path.includes("/.")) {
    throw new Error(`Hidden file rejected: ${path}`);
  }
  // Example: Whitelist specific directories
  if (!path.startsWith("src/") && !path.startsWith("lib/")) {
    throw new Error(`Unexpected path: ${path}`);
  }
}

// Extract to a controlled destination
await archive.extract("./safe-output");
When using files() with a glob pattern, an empty Map is returned if no files match: 
const matches = await archive.files("*.nonexistent");
if (matches.size === 0) {
  console.log("No matching files found");
}

​
Filtering with Glob Patterns

Pass a glob pattern to filter which files are returned: 
// Get only TypeScript files
const tsFiles = await archive.files("**/*.ts");

// Get files in src directory
const srcFiles = await archive.files("src/*");

// Get all JSON files (recursive)
const jsonFiles = await archive.files("**/*.json");

// Get multiple file types with array of patterns
const codeFiles = await archive.files(["**/*.ts", "**/*.js"]);
Supported glob patterns (subset of Bun.Glob syntax):
  • * - Match any characters except /
  • ** - Match any characters including /
  • ? - Match single character
  • [abc] - Match character set
  • {a,b} - Match alternatives
  • !pattern - Exclude files matching pattern (negation). Must be combined with positive patterns; using only negative patterns matches nothing.
See Bun.Glob for the full glob syntax including escaping and advanced patterns.

​
Compression

Bun.Archive supports gzip compression for both reading and writing: 
// Reading: automatically detects gzip
const gzippedTarball = await Bun.file("archive.tar.gz").bytes();
const archive = Bun.Archive.from(gzippedTarball);

// Writing: specify compression
const files = { "hello.txt": "Hello, World!" };
await Bun.Archive.write("output.tar.gz", files, "gzip");

// Getting bytes: specify compression
const gzippedBytes = await archive.bytes("gzip");
The compression argument accepts:
  • "gzip" - Enable gzip compression
  • true - Same as "gzip"
  • false or undefined - No compression

​
Examples

​
Bundle Project Files

import { Glob } from "bun";

// Collect source files
const files: Record<string, string> = {};
const glob = new Glob("src/**/*.ts");

for await (const path of glob.scan(".")) {
  // Normalize path separators to forward slashes for cross-platform compatibility
  const archivePath = path.replaceAll("\\", "/");
  files[archivePath] = await Bun.file(path).text();
}

// Add package.json
files["package.json"] = await Bun.file("package.json").text();

// Create compressed archive
await Bun.Archive.write("bundle.tar.gz", files, "gzip");

​
Extract and Process npm Package

const response = await fetch("https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz");
const archive = Bun.Archive.from(await response.blob());

// Get package.json
const files = await archive.files("package/package.json");
const packageJson = files.get("package/package.json");

if (packageJson) {
  const pkg = JSON.parse(await packageJson.text());
  console.log(`Package: ${pkg.name}@${pkg.version}`);
}

​
Create Archive from Directory

import { readdir } from "node:fs/promises";
import { join } from "node:path";

async function archiveDirectory(dir: string): Promise<Bun.Archive> {
  const files: Record<string, Blob> = {};

  async function walk(currentDir: string, prefix: string = "") {
    const entries = await readdir(currentDir, { withFileTypes: true });

    for (const entry of entries) {
      const fullPath = join(currentDir, entry.name);
      const archivePath = prefix ? `${prefix}/${entry.name}` : entry.name;

      if (entry.isDirectory()) {
        await walk(fullPath, archivePath);
      } else {
        files[archivePath] = Bun.file(fullPath);
      }
    }
  }

  await walk(dir);
  return Bun.Archive.from(files);
}

const archive = await archiveDirectory("./my-project");
await Bun.Archive.write("my-project.tar.gz", archive, "gzip");

​
Reference

Note: The following type signatures are simplified for documentation purposes. See packages/bun-types/bun.d.ts for the full type definitions. 
type ArchiveCompression = "gzip" | boolean;

type ArchiveInput =
  | Record<string, string | Blob | Bun.ArrayBufferView | ArrayBufferLike>
  | Blob
  | Bun.ArrayBufferView
  | ArrayBufferLike;

interface ArchiveExtractOptions {
  /** Glob pattern(s) to filter extraction. Supports negative patterns with "!" prefix. */
  glob?: string | readonly string[];
}

class Archive {
  /**
   * Create an Archive from input data
   */
  static from(data: ArchiveInput): Archive;

  /**
   * Write an archive directly to disk
   */
  static write(path: string, data: ArchiveInput | Archive, compress?: ArchiveCompression): Promise<void>;

  /**
   * Extract archive to a directory
   * @returns Number of entries extracted (files, directories, and symlinks)
   */
  extract(path: string, options?: ArchiveExtractOptions): Promise<number>;

  /**
   * Get archive as a Blob
   */
  blob(compress?: ArchiveCompression): Promise<Blob>;

  /**
   * Get archive as a Uint8Array
   */
  bytes(compress?: ArchiveCompression): Promise<Uint8Array<ArrayBuffer>>;

  /**
   * Get archive contents as File objects (regular files only, no directories)
   */
  files(glob?: string | readonly string[]): Promise<Map<string, File>>;
}