{"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":"python","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,"search_vec":"'2.2.0':52 'activ':45 'altern':32 'analysi':24 'awar':23 'base':15 'capabl':60 'content':22 'content-awar':21 'cross':30 'cross-platform':29 'current':49 'depend':41 'design':10 'detect':3,59,65 'enhanc':58 'file':2,13,64 'fix':62 'identifi':12 'issu':63 'libmag':37 'librari':43 'lightweight':28 'magic':18,36,68 'maintain':46 'mime':66 'modul':9 'number':19,69 'offer':26 'platform':31 'pure':7,70 'puremag':1,4 'python':8,35,71 'python-mag':34 'receiv':54 'regular':55 'runtim':40 'type':14,67 'updat':56 'util':72 'version':50 'zero':39","created_at":"2026-04-09T18:47:57.952928+00:00","updated_at":"2026-04-16T18:15:43.386723+00:00","problems":[{"fix":"Install the library using pip: `pip install puremagic`.","cause":"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.","error":"ModuleNotFoundError: No module named 'puremagic'"},{"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.')`","cause":"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.","error":"puremagic.PureError"},{"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`.","cause":"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.","error":"File 'filename' does not exist!"},{"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.","cause":"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.","error":"puremagic.PureValueError"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/cdgriffith/puremagic","docs":null,"changelog":null,"pypi":"https://pypi.org/project/puremagic/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}