# recursive-unzipper > Recursively extract compressed files that include different formats (`zip`, `xz`, `tar`, `rar`, actually any format). Latest version **1.0.0** (published 2026-04-27) · MIT license · 0 weekly downloads ## Install ```sh npm install recursive-unzipper pnpm add recursive-unzipper yarn add recursive-unzipper bun add recursive-unzipper ``` Provides the command `recursive-unzipper`. ## Health **Score 50/100 (C)** — status: active. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 1.0.0 | | Published | 2026-04-27 | | First published | 2022-08-25 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 4 | | Unpacked size | 66.1 KB | | Known vulnerabilities | 0 (+8 in 2 direct dependencies) | | Install scripts | no | | GitHub stars | 3 | | Author | pillsilly | | Maintainers | pillsilly | ## Links - npm: https://www.npmjs.com/package/recursive-unzipper - Repository: https://github.com/pillsilly/recursive-unzipper - Homepage: https://github.com/pillsilly/recursive-unzipper#readme - Issues: https://github.com/pillsilly/recursive-unzipper/issues - npm.io page: https://npm.io/package/recursive-unzipper ## Dependencies (4) - [tar](https://npm.io/package/tar.md) 7.5.13 - [commander](https://npm.io/package/commander.md) 14.0.3 - [extract-zip](https://npm.io/package/extract-zip.md) 2.0.1 - [lzma-native](https://npm.io/package/lzma-native.md) 8.0.6 ## Recent versions - 1.0.0 (latest) — 2026-04-27 - 1.0.0-0 (beta) — 2026-04-27 - 0.2.1-1 (next) — 2023-04-10 - 0.5.0 — 2026-04-27 - 0.4.0 — 2025-07-26 - 0.3.2 — 2023-10-27 - 0.3.1 — 2023-08-28 - 0.3.0 — 2023-07-28 - 0.2.1 — 2023-04-11 - 0.2.1-0 — 2023-04-10 - 0.2.0 — 2023-03-21 - 0.2.0-beta.0 — 2023-03-17 - 0.1.2 — 2022-10-09 - 0.1.1 — 2022-09-17 - 0.1.0 — 2022-09-16 - … 4 more at https://npm.io/package/recursive-unzipper/versions ## README # recursive-unzipper Recursively extract compressed files that include different formats (`zip`, `xz`, `tar`, `rar`, actually any format). Supports nested formats: e.g., a target `zip` file might contain a `tar` file, which in turn could contain an `xz` or `rar` file. ## Installation ```bash # Global installation npm i recursive-unzipper -g ``` ## API Reference ``` $ recursive-unzipper -h Usage: recursive-unzipper [global options] Arguments: file The first argument is treated as the path of the target file. (Legacy way is through the option "-f") Options: -V, --version Output the version number -f --file [file] Path of the file to be extract -d --dest [destination directory] The destination directory where file will be extracted; if not specified, a same name directory will be created aside of the zip file as the "destination directory" -b --bail If true then it won't continue when error is captured (default: false) -m --map [map] If you are certain about specific type of files were compressed by any of the supported algorithm, e.g, jar can be extracted by zip algorithm; you can then acknowledge recursive-unzipper by passing this flag: e.g --map "jar|zip" --plugin Custom plugin for extraction, e.g. --plugin zip:./plugin.js (default: []) --detect Detect compression type without extracting -h, --help Display help for the command ``` ## Supported Formats `zip`, `xz`, `tar` (built-in) `rar` (not built-in, but supported via custom plugin; see example plugins in the repo's test suite) ### Magic-Byte Detection When a file has no extension or an unrecognized extension, recursive-unzipper automatically detects the compression type by reading the file's magic bytes (file signature). Supported detection: | Format | Signature | Offset | |--------|-----------|--------| | ZIP | `PK\x03\x04` | 0 | | XZ | `\xFD7zXZ\x00` | 0 | | RAR | `Rar!\x1a\x07` | 0 | | TAR | `ustar` | 257 | | TAR (V7) | checksum validation | 0–512 | This means you can extract files even without proper extensions: ```bash recursive-unzipper myfile # detected as zip/xz/tar/rar automatically recursive-unzipper --detect myfile # just report the type, don't extract ``` Magic-byte detection also works for inner files during recursive extraction — if a ZIP contains an extensionless XZ file, it will still be detected and decompressed. ### Custom Extraction Plugins You can provide your own extraction logic for any format using the `--plugin` option. Zip, jar, and xz are built-in, but you can override them with a plugin for special requirements. ```bash recursive-unzipper myfile.rar --plugin rar:./my-rar-extractor.js ``` A plugin should export a function: ```js module.exports = async function(filePath, options) { // Extract filePath to options.dir }; ``` ### RAR Extraction - RAR extraction is not built-in, but you can use the example plugins from the test suite in this repo, or write your own (CLI or pure JS). - See [`test/example-rar.extractor.js`](./test/example-rar.extractor.js) for a CLI-based RAR plugin example, and [`test/example-rar-js.extractor.js`](./test/example-rar-js.extractor.js) for a pure JS RAR plugin example. - For RAR4 archives, use the pure JS plugin. For RAR5 or compressed RAR4, use the CLI plugin. ### Error Handling - If no files are decompressed, extraction fails and logs an error. - If `--bail` is set, extraction stops on the first error. ## For development (using tsx) `npm run run:dev` ## Module Support - mjs: `import {run, detectCompression} from 'recursive-unzipper'` - cjs: `const {run, detectCompression} = require('recursive-unzipper')` `detectCompression(filePath)` returns `'zip' | 'xz' | 'tar' | 'rar' | 'unknown'`. ## Build `npm run compile:prod` ## Lint `npm run lint` ## Run Tests ```bash npm run test ``` ## Test coverage - All archive formats and plugin scenarios are covered by the test suite. - Tests verify both extraction success and file content/structure. ## License [MIT](https://choosealicense.com/licenses/mit/) --- _Source: https://npm.io/package/recursive-unzipper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._