Skip to main content

puremagic

puremagic is a pure python module that will identify a file based off its magic numbers. It has zero runtime dependencies and serves as a lightweight, cross-platform alternative to python-magic/libmagic.

It is designed to be minimalistic and inherently cross platform compatible. It is also designed to be a stand in for python-magic. It implements the functions from_file(filename[, mime]) and from_string(string[, mime]) however the magic_file() and magic_string() are more powerful and will also display confidence and duplicate matches.

Starting with version 2.0, puremagic includes a deep scan system that performs content-aware analysis beyond simple magic number matching. This improves accuracy for formats like Office documents, text files, CSV, MP3, Python source, JSON, HDF5, email, and many scientific formats. Deep scan is enabled by default and can be disabled by setting the environment variable PUREMAGIC_DEEPSCAN=0.

Advantages over using a wrapper for ‘file’ or ‘libmagic’:

  • Faster

  • Lightweight

  • Cross platform compatible

  • No dependencies

Disadvantages:

  • Does not have as many file types

  • No multilingual comments

  • Duplications due to small or reused magic numbers

(Help fix the first two disadvantages by contributing!)

Compatibility

  • Python 3.12+

For use with Python 3.7–3.11, use the 1.x release chain.

Using github ci to run continuous integration tests on listed platforms.

Install from PyPI

$ pip install puremagic

On linux environments, you may want to be clear you are using python3

$ python3 -m pip install puremagic

Usage

“from_file” will return the most likely file extension. “magic_file” will give you every possible result it finds, as well as the confidence.

import puremagic

filename = "test/resources/images/test.gif"

ext = puremagic.from_file(filename)
# '.gif'

puremagic.magic_file(filename)
# [['.gif', 'image/gif', 'Graphics interchange format file (GIF87a)', 0.7],
#  ['.gif', '', 'GIF file', 0.5]]

With “magic_file” it gives each match, highest confidence first:

  • possible extension(s)

  • mime type

  • description

  • confidence (All headers have to perfectly match to make the list, however this orders it by longest header, therefore most precise, first)

If you already have a file open, or raw byte string, you could also use:

  • from_string

  • from_stream

  • magic_string

  • magic_stream

with open(r"test\resources\video\test.mp4", "rb") as file:
    print(puremagic.magic_stream(file))

# [PureMagicWithConfidence(byte_match=b'ftypisom', offset=4, extension='.mp4', mime_type='video/mp4', name='MPEG-4 video', confidence=0.8),
#  PureMagicWithConfidence(byte_match=b'iso2avc1mp4', offset=20, extension='.mp4', mime_type='video/mp4', name='MP4 Video', confidence=0.8)]

Extension and MIME Lookup

To look up a type without a file, use “from_extension” to get the MIME type for an extension, or “from_mime” to get the most likely extension for a MIME type. “magic_extension” and “magic_mime” return every match.

puremagic.from_extension(".pdf")
# 'application/pdf'

puremagic.from_mime("image/jpeg")
# '.jpg'

[m.extension for m in puremagic.magic_mime("image/jpeg")]
# ['.jpg', '.jpe', '.jp2', '.jfif', '.jpeg']

Deep Scan

Deep scan performs content-aware analysis when magic number matching alone is not enough. It is enabled by default and runs automatically as part of the normal identification pipeline.

The following format-specific scanners are included:

  • ZIP — Distinguishes Office formats (xlsx/docx/pptx), OpenDocument (odt/ods/odp), and their macro-enabled variants by inspecting ZIP internals

  • MPEG Audio — Parses MP3/MPEG audio frames to validate and identify audio files

  • Text — Detects text encodings, line endings (CRLF/LF/CR), CSV files with automatic delimiter detection, and email messages (.eml)

  • Python — Validates Python source via ast.parse() and keyword analysis

  • PDF — Format-specific PDF validation

  • JSON — JSON format validation

  • HDF5 — Identifies HDF5 subtypes used in scientific computing (AnnData, Loom, Cooler, BIOM v2, mz5, and more)

  • Audio — Identifies HCOM and SNDR audio formats

  • Dynamic text checks — Recognizes many scientific and bioinformatics text formats including VCF, SAM, GFF, PLY, VTK, and others

To disable deep scan, set the environment variable:

$ export PUREMAGIC_DEEPSCAN=0

Script

Usage

$ python -m puremagic [options] filename <filename2>...

Options

  • -m, --mime — Return the MIME type instead of file extension

  • -v, --verbose — Print verbose output with all possible matches

  • -e, --extension EXT — Look up the MIME type for a file extension

  • -t, --mime-type MIME — Look up the file extension for a MIME type

  • --version — Show program version

Directories can be passed as arguments; all files within will be scanned.

Examples

$ python -m puremagic test/resources/images/test.gif
'test/resources/images/test.gif' : .gif

$ python -m puremagic -m test/resources/images/test.gif test/resources/audio/test.mp3
'test/resources/images/test.gif' : image/gif
'test/resources/audio/test.mp3' : audio/mpeg

Upgrading from 1.x

Version 2.0 includes the following breaking changes:

  • Python 3.12+ required — Python 3.7–3.11 are no longer supported. Use the 1.x release chain for older Python versions.

  • Removed puremagic.what() — The imghdr drop-in replacement has been removed. Use puremagic.from_file() instead.

  • Removed magic_header_array, magic_footer_array, and multi_part_dict from the public API.

  • Removed setup.py — The project now uses pyproject.toml exclusively.

  • Internal functions have been renamed from private (e.g. _magic_data) to public (e.g. magic_data).

FAQ

The file type is actually X but it’s showing up as Y with higher confidence?

This can happen when the file’s signature happens to match a subset of a file standard. The subset signature will be longer, therefore report with greater confidence, because it will have both the base file type signature plus the additional subset one.

Acknowledgements

Gary C. Kessler

For use of his File Signature Tables, available at: https://filesig.search.org/

Freedesktop.org

For use of their shared-mime-info file, available at: https://cgit.freedesktop.org/xdg/shared-mime-info/

License

MIT Licenced, see LICENSE, Copyright (c) 2013-2026 Chris Griffith

Metadata

Release files for puremagic 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for puremagic 2.3.0
File Size Uploaded Provenance Actions
puremagic-2.3.0.tar.gz 1.2 MB With provenance Details for puremagic-2.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for puremagic 2.3.0
File Interpreter ABI Platform Actions
puremagic-2.3.0-py3-none-any.whl Python 3 none any Details for puremagic-2.3.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / puremagic-2.3.0.tar.gz

Download URL puremagic-2.3.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
b54e4a69dd37c50bacc879380f132382ab4e9a935529628c8975abcc73e10640
BLAKE2b-256 checksum
How to use checksums
a78d4d60110e23f445e2dc106340f9bd5f422bb6c540f4fb21086d3ee44b52ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / puremagic-2.3.0-py3-none-any.whl

Download URL puremagic-2.3.0-py3-none-any.whl
Size 73.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
15ce035fe4c3f23e884a105d07448a5a81dd2e297985bdb636928ddf89bb3fe7
BLAKE2b-256 checksum
How to use checksums
8c4072fcaa2f4b850da0207c111be7d2748a57a1c8e8ab149fdc1618323a0b87
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for puremagic 2.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for puremagic-2.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page