# binaryornot

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

- **URL**: https://www.freshcrate.ai/projects/binaryornot
- **Author**: pypi
- **Category**: Developer Tools
- **Latest version**: `0.6.0` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/binaryornot/binaryornot/issues
- **Homepage**: https://pypi.org/project/binaryornot/
- **Language**: Python
- **GitHub**: 147 stars, 45 forks
- **Registry**: pypi (`binaryornot`)
- **Tags**: `pypi`

## 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 function:

```python
from binaryornot.check import is_binary

is_binary(filename)  # returns True or False
```

There's also `is_binary_string()` if you already have bytes:

```python
from binaryornot.helpers import is_binary_string

is_binary_string(b"\x00\x01\x02")  # True
is_binary_string(b"hello world")   # False
```

[Full documentation](https://binaryornot.github.io/binaryornot/) covers the detection algorithm in detail.

## Credits

Created by [Audrey Roy Greenfeld](https://audrey.feldroy.com).

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.6.0` | 2026-04-21 | Low | Imported from PyPI (0.6.0) |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |
| `v0.6.0` | 2026-03-08 | Low | BinaryOrNot identifies binary files three ways: by extension, by file signature, and by content analysis. Pass it any file path and it tells you binary or text, accurately, across PNGs, PDFs, executables, archives, fonts, CJK-encoded text, and hundreds of other formats.  ``` uv pip install --upgrade binaryornot ```  ### What's new  **131 file types recognized by name.** `is_binary()` checks the filename extension against a curated list of binary types (images, audio, video, archives, executables |

## Dependency audit

- **Score**: 100/100
- **Total deps**: 0
- **Resolved**: 0
- **Unresolved**: 0
- **License conflicts**: 0
- **Warnings**: 0
- **Scanned**: 2026-05-25

## Citation

- HTML: https://www.freshcrate.ai/projects/binaryornot
- Markdown: https://www.freshcrate.ai/projects/binaryornot.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/binaryornot/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._