isBinaryFile

Detects if a file is binary in Node.js. Similar to Perl's -B switch, 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.

Note: if the file doesn't exist or is a directory, an error is thrown.

Installation

npm install isbinaryfile

Usage

Returns Promise<boolean> (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 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 below)

isBinaryFileSync(filepath[, options])

Synchronous version of isBinaryFile.

isBinaryFileSync(bytes[, options])

Synchronous version of isBinaryFile for buffers.

Examples

Here's an arbitrary usage:

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:

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

Note: UTF-16 without BOM is automatically detected in most cases without needing a hint.

Testing

Run npm test.

Changelog

6.0.0 (2025-12-05)

⚠ BREAKING CHANGES

• add encoding hints

Features

• add encoding hints (7171398)

Bug Fixes

• fix protobuf processing causing index out of range errors (913ecb0)
• fix protobuf processing causing index out of range errors (d39d2c0)
• handle errors in isBinaryFile function with try-catch 🐛 (ae76dba)
• handle errors in isBinaryFile function with try-catch 🐛 (a78a3b8)
• handle UTF-8 multibyte sequences truncated at buffer boundary (a9d483b)
• handle UTF-8 multibyte sequences truncated at buffer boundary (4832a7c)
• update CI workflow triggers for pull requests 🔧 (298e604)