python-magic

Warnings

• breaking The module name `magic` is also used by other (often older or less maintained) Python packages like `file-magic` or `python-libmagic`. Installing `python-magic` alongside these can lead to import conflicts or unexpected behavior due to incompatible APIs, particularly on Linux distributions like Fedora.
  Fix: Ensure only `python-magic` is installed if you intend to use this library. On systems with pre-installed `python3-file-magic` or `python3-magic` (from OS packages), conflicts may arise. Consider using virtual environments or explicitly uninstalling conflicting packages if you encounter issues.
• gotcha The `python-magic` package is a wrapper around the C `libmagic` library. It does NOT automatically install the underlying system library. You must install `libmagic` separately via your operating system's package manager.
  Fix: Install `libmagic` using your system's package manager (e.g., `sudo apt-get install libmagic1` on Debian/Ubuntu, `brew install libmagic` on macOS). For Windows, consider `pip install python-magic-bin` or `pip install pylibmagic` to get pre-built DLLs.
• gotcha If `libmagic` cannot find its magic database files (e.g., `MagicException: could not find any magic files!`), it means the library is installed but misconfigured.
  Fix: Explicitly provide the path to the magic database file when initializing the `Magic` class: `magic.Magic(magic_file="/path/to/magic.mgc")`. The path varies by OS.
• gotcha On Windows, attempting to use 32-bit `libmagic` DLLs with a 64-bit Python installation will result in a `WindowsError: [Error 193] %1 is not a valid Win32 application`.
  Fix: Ensure that your `libmagic` DLLs match the architecture (32-bit or 64-bit) of your Python installation. Look for 64-bit builds of `libmagic` for Windows or use packages like `python-magic-bin` or `pylibmagic` that provide compatible binaries.
• gotcha The `magic.Magic` class, which provides more direct control over `libmagic` functionality, is explicitly noted as 'not safe for sharing across multiple threads'.
  Fix: Avoid using a single instance of `magic.Magic` across multiple threads. Instantiate `magic.Magic` objects within the thread where they are used, or use the module-level functions (`magic.from_file`, `magic.from_buffer`) which are generally safer for concurrent access.

Install

• pip install python-magic Python package
• sudo apt-get install libmagic1 System dependency (Debian/Ubuntu)
• brew install libmagic System dependency (macOS Homebrew)
• pip install python-magic-bin Optional for Windows (includes libmagic DLLs)

Imports

• magic

  import magic

  The primary package is imported as 'magic'. Be aware of name conflicts with other 'magic'-named libraries like `file-magic` or `python-libmagic` (older/abandoned projects), which may use different import patterns or APIs.

Quickstart

The quickstart demonstrates basic file and buffer type identification using `magic.from_file()` and `magic.from_buffer()`. It also shows how to get the MIME type. A dummy file is created and cleaned up for the example. Note the recommendation to read at least 2048 bytes for `from_buffer` for accurate identification.

import magic
import os

# Create a dummy file for demonstration
with open('test_file.txt', 'w') as f:
    f.write('Hello, python-magic world!')

# Identify file type from a file path
file_type = magic.from_file('test_file.txt')
print(f"File type of 'test_file.txt': {file_type}")

# Identify MIME type from a file path
mime_type = magic.from_file('test_file.txt', mime=True)
print(f"MIME type of 'test_file.txt': {mime_type}")

# Identify file type from a buffer
with open('test_file.txt', 'rb') as f:
    buffer_content = f.read(2048) # Recommend reading at least the first 2048 bytes
buffer_type = magic.from_buffer(buffer_content)
print(f"File type from buffer: {buffer_type}")

# Clean up the dummy file
os.remove('test_file.txt')

# Using the Magic class for more control (e.g., specifying magic database file)
# Note: The Magic class is not safe for sharing across multiple threads
# f = magic.Magic(uncompress=True)
# decompressed_type = f.from_file('testdata/test.gz')
# print(f"Decompressed type: {decompressed_type}")