Install & Compatibility
Where this runs
tested against v0.4.27 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
magic
✓ import magic
✗ from libmagic 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.
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}")
Debug
Known issues
breakingThe 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.fixEnsure 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.
affects: All versions
gotchaThe `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.fixInstall `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.
affects: All versions
gotchaIf `libmagic` cannot find its magic database files (e.g., `MagicException: could not find any magic files!`), it means the library is installed but misconfigured.fixExplicitly 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.
affects: All versions
gotchaOn 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`.fixEnsure 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.
affects: All versions on Windows
gotchaThe `magic.Magic` class, which provides more direct control over `libmagic` functionality, is explicitly noted as 'not safe for sharing across multiple threads'.fixAvoid 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.
affects: All versions
gotchaThe package `python-magic-bin` is specifically designed for Windows to provide pre-built `libmagic` DLLs. Attempting to install it on other operating systems (e.g., Linux or macOS) will result in a `No matching distribution found` error, as it is not available on PyPI for those platforms.fixOn Linux or macOS, install `libmagic` using your system's package manager (e.g., `sudo apt-get install libmagic1` on Debian/Ubuntu, `brew install libmagic` on macOS). `python-magic-bin` is not needed or available on these platforms.
affects: All versions (when installing on non-Windows OS)
Errors
Common errors & fixes
magic.MagicException: failed to find libmagic
The underlying `libmagic` C library or its data files are not installed or are not discoverable by `python-magic` on your system.
fixInstall the `libmagic` C library using your system's package manager (e.g., `apt-get install libmagic1`, `brew install libmagic`, `yum install file-devel`).
ModuleNotFoundError: No module named 'magic'
The `python-magic` library has not been installed in the current Python environment.
fixInstall the library using pip: `pip install python-magic`.
AttributeError: module 'magic' has no attribute 'fromfile'
This error occurs when attempting to call a method with a typo (e.g., `fromfile` instead of `from_file`) or an incorrect method name that does not exist in the `magic` module.
fixCorrect the method name to one of the available functions, such as `magic.from_file(filepath)` for files or `magic.from_buffer(data)` for bytes.
Upgrade
Version history
0.4.27latest on PyPI · released Jun 7, 2022
Audit
Dependencies
libmagicrequiredCore functionality relies on the C `libmagic` library, which must be installed separately on the system.
python-magic-binoptionalProvides pre-built `libmagic` DLLs for Windows, simplifying installation when system-level installation is problematic.
pylibmagicoptionalA lightweight, minimal Python package that ships `libmagic` libraries, offering a cross-platform solution for the `libmagic` dependency.