Registry / serialization / tar
library7.5.13jsnpmunverified

node-tar is a robust and fast full-featured library for creating and extracting tar archives in Node.js, designed to mimic the `tar(1)` utility on Unix systems. The current stable version is 7.5.13, requiring Node.js >=18. It prioritizes security, implementing extensive hardening measures against various filesystem-based attacks, such as path traversal, symbolic link manipulation, and malicious file types, especially critical for use cases like the npm registry. Unlike many ad-hoc tar implementations, node-tar has undergone years of scrutiny and intensive use, making it one of the most secure JavaScript tar extractors available. While it doesn't have a fixed release cadence, updates are issued as needed for bug fixes, security patches, or feature enhancements.

npm install tar
INSTALL
IMPORT
SIG · TAR
T
tar
serializationjavascriptv7.5.13
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create
import { create } from 'tar';
const tar = require('tar'); tar.create(...);
Named export for creating tar archives. CommonJS 'require' style is generally discouraged for modern Node.js applications (>=18).
extract
import { extract } from 'tar';
import tar from 'tar'; tar.extract(...);
Named export for extracting tar archives. The library does not offer a default export for direct tar operations.
*
import * as tar from 'tar';
const tar = require('tar');
Imports all named exports into a 'tar' namespace object. This is the recommended way to use the library if you need multiple functions like `create`, `extract`, `list`, etc.
TarOptions
import type { TarOptions } from 'tar';
Type import for configuration options when interacting with tar archives, essential for TypeScript users to ensure type safety.

Demonstrates how to create a non-gzipped tar archive from a directory and then extract its contents into a new location using `node-tar`.

import { create, extract } from 'tar'; import { promises as fs } from 'fs'; import path from 'path'; async function createAndExtractTarball() { const dir = 'test_files'; const tarballName = 'test_archive.tar'; const extractDir = 'extracted_files'; // 1. Create a directory and some files await fs.mkdir(dir, { recursive: true }); await fs.writeFile(path.join(dir, 'file1.txt'), 'Hello from file 1!'); await fs.writeFile(path.join(dir, 'file2.js'), 'console.log("Hello from file 2!");'); console.log(`Created directory '${dir}' with two files.`); // 2. Create a tarball from the directory await create( { gzip: false, file: tarballName, cwd: '.' }, [dir] ); console.log(`Created tarball '${tarballName}'.`); // 3. Extract the tarball into a new directory await fs.mkdir(extractDir, { recursive: true }); await extract( { file: tarballName, cwd: extractDir, strip: 1 }, [] ); console.log(`Extracted '${tarballName}' into '${extractDir}'.`); // 4. Verify extraction (optional) const extractedFiles = await fs.readdir(path.join(extractDir, dir)); console.log('Files in extracted directory:', extractedFiles); // 5. Clean up await fs.rm(dir, { recursive: true, force: true }); await fs.rm(tarballName, { force: true }); await fs.rm(extractDir, { recursive: true, force: true }); console.log('Cleaned up created files and directories.'); } createAndExtractTarball().catch(console.error);
Debug
Known issues
gotchaWhen extracting tarball data, never use a folder that could be potentially controlled by an unknown actor. An attacker could swap out the target of an extracted file with a symbolic link to write files outside the intended target folder. This is a fundamental TOCTOU (Time-of-Check to Time-of-Use) vulnerability that cannot be entirely hardened against by the library itself.
fix
Ensure the extraction target directory and its parent directories are owned and controlled only by trusted processes. Always extract into a newly created, isolated directory.
affects: all
breakingPrior versions (specifically v6.x) may have issues with `minipass` versions, as seen in the v6.1.13 changelog. While not directly a breaking change for `node-tar`'s API, older `minipass` versions could introduce unexpected stream behavior or performance issues.
fix
Update to the latest `node-tar` (v7.x or higher) to ensure compatibility with modern `minipass` versions and leverage the latest security patches and features.
affects: <7.0.0
gotchaWhen unpacking tarballs from unknown sources, it is highly recommended to use a filter function that rejects all hardlinks and symbolic links. These file types are historically the root of nearly every file extraction vulnerability. The `npm` registry, for instance, filters these out of package artifacts.
fix
Implement a `filter` option during extraction, e.g., `tar.extract({ ..., filter: (path, stat) => !stat.isSymbolicLink() && !stat.isFile() /* for hardlinks */ }, ...)`.
affects: all
gotchaFor compressed tarballs (gzip, brotli, zstd) from unknown sources, filter out excessively large files. Even if the archive size is restricted, a small compressed file can decompress into a massive file, leading to disk space exhaustion (a 'zip bomb' variant).
fix
Use the `filter` option during extraction to check `stat.size` against a reasonable maximum, e.g., `tar.extract({ ..., filter: (path, stat) => stat.size < MAX_FILE_SIZE_BYTES }, ...)`.
affects: all
breakingOlder versions of `node-tar` (pre-v7) are not actively maintained or tested for newly discovered security advisories. They should be assumed to contain all known and potentially unknown security vulnerabilities.
fix
Always stay up to date with the latest major version of `node-tar`. Upgrade to v7.x or later to benefit from ongoing maintenance, security hardening, and bug fixes.
affects: <7.0.0
Errors
Common errors & fixes
TypeError: tar.create is not a function
Attempting to use `require('tar')` and then call `tar.create` directly, or using a default import instead of a named import.
fix
Use named imports: `import { create } from 'tar';` or `import * as tar from 'tar';` then `tar.create(...)`.
Error: EACCES: permission denied, open 'path/to/file'
The Node.js process does not have sufficient read or write permissions for the specified file or directory during tarball creation or extraction.
fix
Ensure the Node.js process has appropriate file system permissions. If extracting, consider changing the `cwd` option or running with elevated privileges (with caution, especially for untrusted archives).
Error: no such file or directory, open 'my-archive.tar'
The specified tarball file for extraction (`file` option) does not exist at the given path, or the `cwd` option is incorrect.
fix
Verify the `file` path and the `cwd` option are correct and point to an existing tarball. Use `path.resolve()` for absolute paths if necessary.
WARN: Skipping symlink 'malicious-link' -> 'outside-dir'
node-tar's security features detected a symbolic or hard link attempting to target a location outside the extraction folder, or another forbidden path manipulation, and safely skipped it.
fix
This is generally a security feature working as intended. If you *intended* to allow such links, set `preservePaths: true` (with extreme caution, as it disables many security protections) or implement a custom `filter` function to allow specific links after careful validation.
Upgrade
Version history
7.5.13latest on npm
Audit
Dependencies
minipassrequiredCore streaming library for processing data within tar operations.
Agent activity
3 hits · last 30 days
node
2
Resources
tar — npm install tar · libregistry