{"id":2204,"library":"puremagic","title":"Puremagic: File Detection","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/cdgriffith/puremagic","tags":["file detection","mime type","magic numbers","pure python","utility"],"install":[{"cmd":"pip install puremagic","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The library is imported as a single module.","symbol":"puremagic","correct":"import puremagic"}],"quickstart":{"code":"import puremagic\nimport os\n\n# Create a dummy file for demonstration\ndummy_filename = \"test_file.txt\"\nwith open(dummy_filename, \"w\") as f:\n    f.write(\"This is a test text file.\")\n\n# Get the most likely file extension\nextension = puremagic.from_file(dummy_filename)\nprint(f\"Detected extension: {extension}\")\n\n# Get all possible results with confidence and MIME type\nresults = puremagic.magic_file(dummy_filename)\nprint(f\"All detection results: {results}\")\n\n# Clean up the dummy file\nos.remove(dummy_filename)\n\n# Example with an in-memory string\ndata_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'\nstring_results = puremagic.magic_string(data_string)\nprint(f\"String detection results: {string_results}\")","lang":"python","description":"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()`."},"warnings":[{"fix":"Upgrade your Python environment to 3.12+ or use the 1.x release chain for older Python versions.","message":"Version 2.0.0 removed support for Python versions 3.7 through 3.11. Puremagic now requires Python 3.12 or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace calls to `puremagic.what()` with `puremagic.from_file()` for similar functionality.","message":"The `puremagic.what()` function, a drop-in replacement for `imghdr`, was removed in version 2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update any code that relies on the exact MIME type string for WAV files to use `audio/wav`.","message":"The MIME type for WAV files changed from `audio/wave` to `audio/wav` in version 2.1.0.","severity":"breaking","affected_versions":">=2.1.0"},{"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`.","message":"Starting 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}