puremagic

library2.2.0pypypi✓ verified 26d ago

Puremagic is a pure Python module designed to identify file types based on their 'magic numbers' and content-aware analysis. It offers a lightweight, cross-platform alternative to `python-magic`/`libmagic` with zero runtime dependencies. The library is actively maintained, with its current version being 2.2.0, and receives regular updates to enhance detection capabilities and fix issues.

serialization devops

pip install puremagic

github ↗package ↗

INSTALL

IMPORT

SIG · PUREMAGIC

puremagic

serializationpythonv2.2.0

Install

1.6s avg

Import

60ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.30 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.060s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.060s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

puremagic

✓ import puremagic

The library is imported as a single module.

This quickstart demonstrates how to use `puremagic.from_file()` to get the most likely file extension and `puremagic.magic_file()` to retrieve all detected magic numbers, MIME types, and confidence levels. It also includes an example for in-memory string detection using `puremagic.magic_string()`.

import puremagic import os # Create a dummy file for demonstration dummy_filename = "test_file.txt" with open(dummy_filename, "w") as f: f.write("This is a test text file.") # Get the most likely file extension extension = puremagic.from_file(dummy_filename) print(f"Detected extension: {extension}") # Get all possible results with confidence and MIME type results = puremagic.magic_file(dummy_filename) print(f"All detection results: {results}") # Clean up the dummy file os.remove(dummy_filename) # Example with an in-memory string data_string = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\nIDATx\xda\xed\xc1\x01\x01\x00\x00\x00\xc2\xa0\xf7Om\x00\x00\x00\x00IEND\xaeB`\x82' string_results = puremagic.magic_string(data_string) print(f"String detection results: {string_results}")

Debug

Known issues

breakingVersion 2.0.0 removed support for Python versions 3.7 through 3.11. Puremagic now requires Python 3.12 or newer.

fix

Upgrade your Python environment to 3.12+ or use the 1.x release chain for older Python versions.

affects: >=2.0.0

breakingThe `puremagic.what()` function, a drop-in replacement for `imghdr`, was removed in version 2.0.0.

fix

Replace calls to `puremagic.what()` with `puremagic.from_file()` for similar functionality.

affects: >=2.0.0

breakingThe MIME type for WAV files changed from `audio/wave` to `audio/wav` in version 2.1.0.

fix

Update any code that relies on the exact MIME type string for WAV files to use `audio/wav`.

affects: >=2.1.0

gotchaStarting with version 2.0.0, deep scanning for improved accuracy is enabled by default. This changes the detection behavior for many file types (e.g., Office documents, text files, JSON) compared to earlier versions.

fix

Review existing code and expected outputs, especially for files that were ambiguously identified before. If necessary, deep scan can be disabled by setting the environment variable `PUREMAGIC_DEEPSCAN=0`.

affects: >=2.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'puremagic'

The `puremagic` library is not installed in the Python environment, or the environment where the code is run does not have access to the installed library.

fix

Install the library using pip: `pip install puremagic`.

puremagic.PureError

This error is raised by `puremagic` when it cannot determine the file type from the provided data or file path, meaning it doesn't have a matching 'magic number' or content signature in its database for the given input.

fix

Handle the `puremagic.PureError` exception in your code to gracefully manage cases where a file type cannot be identified. For example: `try: ext = puremagic.from_file(filename) except puremagic.PureError: print('File type could not be determined.')`

File 'filename' does not exist!

When using the `puremagic` command-line tool or its `from_file` function, this message indicates that the specified file path does not point to an existing file.

fix

Ensure that the file path provided to `puremagic` is correct and that the file exists at that location. Use an absolute path or verify the relative path from your current working directory. For example, `puremagic my_existing_file.txt` or `puremagic /path/to/my_file.jpg`.

puremagic.PureValueError

This error is raised by `puremagic` when invalid input is provided to its functions, such as an empty string where file content is expected, or an invalid argument type.

fix

Review the input passed to the `puremagic` function that raised the error. Ensure that file contents are not empty, paths are valid strings, and any optional arguments adhere to the expected types and formats.

Upgrade

Version history

2.2.0latest on PyPI · released Apr 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

Resources

githubhttps://github.com/cdgriffith/puremagic ↗

packagehttps://pypi.org/project/puremagic/ ↗