---
id: binaryornot
version: "0.6.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# binaryornot — Ultra-lightweight pure Python package to check if a file is binary or text.

License: permissive · Maintenance: active · Popularity: top 1,000 on PyPI

## Install

pip install binaryornot
uv add binaryornot
poetry add binaryornot

## Description

# BinaryOrNot

Python library and CLI tool to check if a file is binary or text. Zero dependencies.

```python
from binaryornot.check import is_binary

is_binary("image.png")    # True
is_binary("README.md")    # False
is_binary("data.sqlite")  # True
is_binary("report.csv")   # False
```

```sh
$ binaryornot image.png
True
```

## Install

```sh
pip install binaryornot
```

## Why not just check for null bytes?

That's the first thing everyone tries. It works until it doesn't:

- A UTF-16 text file is full of null bytes. Your tool thinks it's binary and corrupts it.
- A Big5 or GB2312 text file has high-ASCII bytes everywhere. Looks binary by byte ratios alone.
- A font file (.woff, .eot) is clearly binary but might not have null bytes in the first chunk.

BinaryOrNot reads the first 128 bytes and runs them through a trained decision tree that considers byte ratios, Shannon entropy, encoding validity, BOM detection, and more. It handles all the edge cases above correctly, with zero dependencies.

Tested against [37 text encodings and 49 binary formats](https://binaryornot.github.io/binaryornot/usage/), verified by parametrized tests driven from coverage CSVs.

## API

One...

## AI interpretation — verify before relying

Detects whether a file is binary or text by analyzing byte patterns, encoding validity, and entropy rather than relying on null-byte heuristics alone. Includes both a Python API and command-line tool.

Verdict: A mature, well-maintained utility with zero dependencies, permissive licensing, and no known vulnerabilities. Production-ready for file-type classification tasks where naive null-byte checks fail—particularly useful in text-processing pipelines that must handle diverse encodings and binary formats correctly.

[View on SkillFed](https://skillfed.io/packages/binaryornot) · [View on PyPI](https://pypi.org/project/binaryornot/)