Python libmagic bindings

1.0 · active · verified Fri Apr 17

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.

Common errors

```
magic.MagicException: failed to find libmagic. Check your installation
```
cause The underlying `libmagic` C library (e.g., `libmagic.so`, `libmagic.dll`) is not installed or not found by the Python bindings.

fix Install the C `libmagic` library on your operating system. For Debian/Ubuntu: `sudo apt-get install libmagic1`. For macOS (Homebrew): `brew install libmagic`.
```
AttributeError: module 'magic' has no attribute 'Magic'
```
cause Incorrect import statement. You are likely doing `import magic` and then trying `magic.Magic()` instead of importing the class directly.

fix Change your import statement to `from magic import Magic`.
```
IsADirectoryError: [Errno 21] Is a directory: '/path/to/my_directory'
```
cause `Magic().from_file()` was called with a path pointing to a directory, not an actual file.

fix Ensure the path argument to `from_file()` refers to a regular file. You can use `os.path.isfile(path)` to check this beforehand.
```
OSError: [Errno 2] No such file or directory: '/path/to/nonexistent_file.txt'
```
cause The file path provided to `Magic().from_file()` does not exist on the filesystem.

fix Verify that the file path is correct and that the file actually exists at the specified location.

Warnings

gotcha The `libmagic` Python package is a binding to the `libmagic` C library, which must be installed separately on your operating system.
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`.
gotcha Using `Magic().from_file()` on a directory path will result in an `IsADirectoryError`.
Fix: Always verify that the path provided to `from_file()` points to an actual file, for example, by using `os.path.isfile(path)`.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install libmagic Install Python package

Imports

Magic
wrong:
```
import libmagic
```
correct:
```
from magic import Magic
```
The primary class for file identification is `Magic`, located within the `magic` module, not `libmagic`.

Quickstart

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.

import os
from magic import Magic

# Create a dummy file for demonstration
dummy_file_path = "test_file_for_libmagic.txt"
with open(dummy_file_path, "w") as f:
    f.write("This is a plain text file content.")

try:
    # Initialize Magic - often detects libmagic automatically
    # If not, you might need to specify the path to your magic.mgc file:
    # m = Magic(magic_file='/usr/share/misc/magic.mgc')
    m = Magic()

    # Get file type description from a file
    file_description = m.from_file(dummy_file_path)
    print(f"File '{dummy_file_path}' description: {file_description}")

    # Get file type from a byte buffer
    buffer_data = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR..."
    buffer_description = m.from_buffer(buffer_data)
    print(f"Buffer data description: {buffer_description}")

    # Get MIME type explicitly
    m_mime = Magic(mime=True)
    mime_type = m_mime.from_file(dummy_file_path)
    print(f"File '{dummy_file_path}' MIME type: {mime_type}")

finally:
    # Clean up the dummy file
    if os.path.exists(dummy_file_path):
        os.remove(dummy_file_path)

view raw JSON →