binaryornot

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

binaryornot Permissive license MIT Active ★ 149 v0.6.0 released 2026-03-08

Install

binaryornot on PyPI

pip

pip install binaryornot

uv

uv add binaryornot

poetry

poetry add binaryornot

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.10)
Install friction	low — pure-Python wheel
Runtime dependencies	none
Maintenance	actively maintained — 158 days since the last release
Last repo commit	2026-05-19
First released	2013-08-17
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: binaryornot-0.6.0-py3-none-any.whl

Development Status :: 5 - Production/StableIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Typing :: Typed

About binaryornot

from the package's own PyPI description — quoted content, verbatim

BinaryOrNot

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

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

$ binaryornot image.png
True

Install

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, verified by parametrized tests driven from coverage CSVs.

API

One...

Read as markdown · JSON record · Source repository · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

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.

Exceptionally low friction: zero runtime dependencies, pure Python wheel, and active maintenance with a recent release (158 days ago). Last commit on 2026-05-19 confirms ongoing support.

MIT license (permissive) imposes no restrictions on commercial or private use, modification, or redistribution, only requiring attribution.

Usage

pip install binaryornot
from binaryornot.check import is_binary
is_binary("image.png")  # True
is_binary("README.md")  # False

Requires Python 3.10 or later (supports 3.10–3.14).

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.

Needs verification

Whether the decision-tree model's accuracy claims against 37 text encodings and 49 binary formats hold in your specific use cases.
Performance characteristics when processing large files or high-volume batches (fact sheet does not quantify throughput).

binary file detectiontext vs binary classifierfile type checkeris file binaryencoding detectionbinary content analysisfile format identification