# isbinaryfile > Detects if a file is binary in Node.js. Similar to Perl's -B. Latest version **6.0.0** (published 2025-12-05) · MIT license · 0 weekly downloads ## Install ```sh npm install isbinaryfile pnpm add isbinaryfile yarn add isbinaryfile bun add isbinaryfile ``` ## Health **Score 70/100 (B)** — status: stable. Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 6.0.0 | | Published | 2025-12-05 | | First published | 2012-10-09 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >= 24.0.0 | | Dependencies | 0 | | Unpacked size | 19.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 176 | | Maintainers | gjtorikian | | Keywords | text, binary, encoding, istext, is text, isbinary, is binary, is text or binary, is text or binary file, isbinaryfile, is binary file, istextfile, is text file | ## Links - npm: https://www.npmjs.com/package/isbinaryfile - Repository: https://github.com/gjtorikian/isBinaryFile - Homepage: https://github.com/gjtorikian/isBinaryFile#readme - Issues: https://github.com/gjtorikian/isBinaryFile/issues - Funding: https://github.com/sponsors/gjtorikian/ - npm.io page: https://npm.io/package/isbinaryfile ## Alternatives - [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads - [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads - [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads - [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads - [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads ## Recent versions - 6.0.0 (latest) — 2025-12-05 - 5.0.7 — 2025-11-11 - 5.0.6 — 2025-08-28 - 5.0.5 — 2025-08-28 - 5.0.4 — 2024-10-23 - 5.0.3 — 2024-10-13 - 5.0.2 — 2024-02-14 - 5.0.1 — 2024-02-14 - 5.0.0 — 2022-03-25 - 4.0.10 — 2022-03-25 - 4.0.9 — 2022-03-24 - 4.0.8 — 2021-04-29 - 4.0.6 — 2020-04-03 - 4.0.5 — 2020-03-17 - 4.0.4 — 2020-01-12 - … 26 more at https://npm.io/package/isbinaryfile/versions ## README # isBinaryFile Detects if a file is binary in Node.js. Similar to [Perl's `-B` switch](http://stackoverflow.com/questions/899206/how-does-perl-know-a-file-is-binary), in that: - it reads the first few thousand bytes of a file - checks for a `null` byte; if it's found, it's binary - flags non-ASCII characters. After a certain number of "weird" characters, the file is flagged as binary Much of the logic is pretty much ported from [ag](https://github.com/ggreer/the_silver_searcher). Note: if the file doesn't exist or is a directory, an error is thrown. ## Installation ``` npm install isbinaryfile ``` ## Usage Returns `Promise` (or just `boolean` for `*Sync`). `true` if the file is binary, `false` otherwise. ### isBinaryFile(filepath[, options]) - `filepath` - a `string` indicating the path to the file. - `options` - an optional object with the following properties: - `encoding` - an encoding hint (see [Encoding Hints](#encoding-hints) below) ### isBinaryFile(bytes[, options]) - `bytes` - a `Buffer` of the file's contents. - `options` - an optional object with the following properties: - `size` - the size of the buffer (defaults to `bytes.length`) - `encoding` - an encoding hint (see [Encoding Hints](#encoding-hints) below) ### isBinaryFileSync(filepath[, options]) Synchronous version of `isBinaryFile`. ### isBinaryFileSync(bytes[, options]) Synchronous version of `isBinaryFile` for buffers. ### Examples Here's an arbitrary usage: ```javascript import { isBinaryFile, isBinaryFileSync } from 'isbinaryfile'; import fs from 'fs'; const filename = 'fixtures/pdf.pdf'; // Async with file path const result = await isBinaryFile(filename); if (result) { console.log('It is binary!'); } else { console.log('No it is not.'); } // Sync with buffer const bytes = fs.readFileSync(filename); console.log(isBinaryFileSync(bytes)); // true or false // With explicit size option const partialBuffer = Buffer.alloc(100); fs.readSync(fs.openSync(filename, 'r'), partialBuffer, 0, 100, 0); console.log(isBinaryFileSync(partialBuffer, { size: 100 })); ``` ### Encoding Hints For files that use non-UTF-8 encodings, you can provide encoding hints to improve detection accuracy: ```javascript import { isBinaryFile, isBinaryFileSync } from 'isbinaryfile'; // UTF-16 files without BOM are auto-detected in most cases const result1 = await isBinaryFile('utf16-file.txt'); // Or provide explicit encoding hint const result2 = await isBinaryFile('utf16-file.txt', { encoding: 'utf-16' }); // ISO-8859-1 / Latin-1 encoded files const result3 = isBinaryFileSync('german-text.txt', { encoding: 'latin1' }); // CJK encoded files (Big5, GB2312, EUC-KR, etc.) const result4 = isBinaryFileSync('chinese-big5.txt', { encoding: 'big5' }); const result5 = isBinaryFileSync('korean-text.txt', { encoding: 'euc-kr' }); // Generic CJK hint when exact encoding is unknown const result6 = isBinaryFileSync('asian-text.txt', { encoding: 'cjk' }); ``` #### Supported Encoding Hints | Hint | Description | | ------------ | ------------------------------------------ | | `utf-16` | UTF-16 (auto-detect endianness) | | `utf-16le` | UTF-16 Little Endian | | `utf-16be` | UTF-16 Big Endian | | `latin1` | ISO-8859-1 / Latin-1 | | `iso-8859-1` | Alias for latin1 | | `cjk` | Generic CJK (use when encoding is unknown) | | `big5` | Traditional Chinese | | `gb2312` | Simplified Chinese | | `gbk` | Extended GB2312 | | `euc-kr` | Korean | | `shift-jis` | Japanese | **Note:** UTF-16 without BOM is automatically detected in most cases without needing a hint. ## Testing Run `npm test`. --- _Source: https://npm.io/package/isbinaryfile · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._