{"id":9889,"library":"libmagic","title":"Python libmagic bindings","description":"libmagic provides Python bindings to the `libmagic` C library, which identifies file types by checking their 'magic numbers' and other patterns. It's a thin wrapper around the venerable `file` command-line utility. The current version is 1.0, and it generally follows a stable, low-cadence release cycle focusing on maintenance and compatibility with the underlying C library.","status":"active","version":"1.0","language":"en","source_language":"en","source_url":"https://github.com/python-libmagic/python-libmagic","tags":["file-type","magic-number","bindings","identification","mime-type"],"install":[{"cmd":"pip install libmagic","lang":"bash","label":"Install Python package"}],"dependencies":[],"imports":[{"note":"The primary class for file identification is `Magic`, located within the `magic` module, not `libmagic`.","wrong":"import libmagic","symbol":"Magic","correct":"from magic import Magic"}],"quickstart":{"code":"import os\nfrom magic import Magic\n\n# Create a dummy file for demonstration\ndummy_file_path = \"test_file_for_libmagic.txt\"\nwith open(dummy_file_path, \"w\") as f:\n    f.write(\"This is a plain text file content.\")\n\ntry:\n    # Initialize Magic - often detects libmagic automatically\n    # If not, you might need to specify the path to your magic.mgc file:\n    # m = Magic(magic_file='/usr/share/misc/magic.mgc')\n    m = Magic()\n\n    # Get file type description from a file\n    file_description = m.from_file(dummy_file_path)\n    print(f\"File '{dummy_file_path}' description: {file_description}\")\n\n    # Get file type from a byte buffer\n    buffer_data = b\"\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR...\"\n    buffer_description = m.from_buffer(buffer_data)\n    print(f\"Buffer data description: {buffer_description}\")\n\n    # Get MIME type explicitly\n    m_mime = Magic(mime=True)\n    mime_type = m_mime.from_file(dummy_file_path)\n    print(f\"File '{dummy_file_path}' MIME type: {mime_type}\")\n\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dummy_file_path):\n        os.remove(dummy_file_path)\n","lang":"python","description":"This quickstart demonstrates how to use `libmagic` to identify file types from both actual files and byte buffers. It also shows how to retrieve the MIME type. A crucial first step not shown here is installing the underlying C `libmagic` library."},"warnings":[{"fix":"Before `pip install libmagic`, ensure the C library is present. For Debian/Ubuntu: `sudo apt-get install libmagic1`. For macOS (Homebrew): `brew install libmagic`. For Fedora/RHEL: `sudo dnf install file-libs`.","message":"The `libmagic` Python package is a binding to the `libmagic` C library, which must be installed separately on your operating system.","severity":"gotcha","affected_versions":"1.x"},{"fix":"Always verify that the path provided to `from_file()` points to an actual file, for example, by using `os.path.isfile(path)`.","message":"Using `Magic().from_file()` on a directory path will result in an `IsADirectoryError`.","severity":"gotcha","affected_versions":"1.x"},{"fix":"You may need to set the `MAGIC_FILE` environment variable to the full path of `magic.mgc` (the database file) or `LIBMAGIC_PATH` to the shared library (`libmagic.so`, `libmagic.dylib`, `libmagic.dll`) before running your Python script.","message":"If the `libmagic` C library is installed in a non-standard location (e.g., custom Homebrew prefix or system without standard paths), the Python bindings might fail to find it.","severity":"gotcha","affected_versions":"1.x"},{"fix":"While `libmagic` itself handles various encodings, the Python bindings typically return Unicode strings. If parsing output, be aware of character sets. For MIME types, specify `mime=True` in the `Magic` constructor.","message":"When dealing with filenames or file content that might contain non-ASCII characters, ensure your system's locale settings and Python's string handling are consistent to avoid encoding issues.","severity":"gotcha","affected_versions":"1.x"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the C `libmagic` library on your operating system. For Debian/Ubuntu: `sudo apt-get install libmagic1`. For macOS (Homebrew): `brew install libmagic`.","cause":"The underlying `libmagic` C library (e.g., `libmagic.so`, `libmagic.dll`) is not installed or not found by the Python bindings.","error":"magic.MagicException: failed to find libmagic. Check your installation"},{"fix":"Change your import statement to `from magic import Magic`.","cause":"Incorrect import statement. You are likely doing `import magic` and then trying `magic.Magic()` instead of importing the class directly.","error":"AttributeError: module 'magic' has no attribute 'Magic'"},{"fix":"Ensure the path argument to `from_file()` refers to a regular file. You can use `os.path.isfile(path)` to check this beforehand.","cause":"`Magic().from_file()` was called with a path pointing to a directory, not an actual file.","error":"IsADirectoryError: [Errno 21] Is a directory: '/path/to/my_directory'"},{"fix":"Verify that the file path is correct and that the file actually exists at the specified location.","cause":"The file path provided to `Magic().from_file()` does not exist on the filesystem.","error":"OSError: [Errno 2] No such file or directory: '/path/to/nonexistent_file.txt'"}]}