python-magic

0.4.27 verified Tue May 12 auth: no python install: stale

python-magic is a Python interface to the `libmagic` file type identification library. `libmagic` identifies file types by checking their headers according to a predefined list of file types. This functionality is exposed to the command line by the Unix `file` command. The current version is 0.4.27, with releases occurring infrequently, often with several months or years between updates.

pip install python-magic

Common errors

error magic.MagicException: failed to find libmagic ↓

cause The underlying `libmagic` C library or its data files are not installed or are not discoverable by `python-magic` on your system.

fix

Install the libmagic C library using your system's package manager (e.g., apt-get install libmagic1, brew install libmagic, yum install file-devel).

error ModuleNotFoundError: No module named 'magic' ↓

cause The `python-magic` library has not been installed in the current Python environment.

fix

Install the library using pip: pip install python-magic.

error AttributeError: module 'magic' has no attribute 'fromfile' ↓

cause 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.

fix

Correct the method name to one of the available functions, such as magic.from_file(filepath) for files or magic.from_buffer(data) for bytes.

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.

gotcha The 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. ↓

fix On 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.

Install

sudo apt-get install libmagic1

brew install libmagic

pip install python-magic-bin

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) python-magic wheel - - 17.8M

3.10 alpine (musl) python-magic - - - -

3.10 alpine (musl) python-magic-bin build_error - - - -

3.10 alpine (musl) python-magic-bin - - - -

3.10 slim (glibc) python-magic wheel 1.4s - 18M

3.10 slim (glibc) python-magic - - - -

3.10 slim (glibc) python-magic-bin build_error - 1.3s - -

3.10 slim (glibc) python-magic-bin - - - -

3.11 alpine (musl) python-magic wheel - - 19.7M

3.11 alpine (musl) python-magic - - - -

3.11 alpine (musl) python-magic-bin build_error - - - -

3.11 alpine (musl) python-magic-bin - - - -

3.11 slim (glibc) python-magic wheel 1.5s - 20M

3.11 slim (glibc) python-magic - - - -

3.11 slim (glibc) python-magic-bin build_error - 1.4s - -

3.11 slim (glibc) python-magic-bin - - - -

3.12 alpine (musl) python-magic wheel - - 11.6M

3.12 alpine (musl) python-magic - - - -

3.12 alpine (musl) python-magic-bin build_error - - - -

3.12 alpine (musl) python-magic-bin - - - -

3.12 slim (glibc) python-magic wheel 1.4s - 12M

3.12 slim (glibc) python-magic - - - -

3.12 slim (glibc) python-magic-bin build_error - 1.4s - -

3.12 slim (glibc) python-magic-bin - - - -

3.13 alpine (musl) python-magic wheel - - 11.3M

3.13 alpine (musl) python-magic - - - -

3.13 alpine (musl) python-magic-bin build_error - - - -

3.13 alpine (musl) python-magic-bin - - - -

3.13 slim (glibc) python-magic wheel 1.4s - 12M

3.13 slim (glibc) python-magic - - - -

3.13 slim (glibc) python-magic-bin build_error - 1.4s - -

3.13 slim (glibc) python-magic-bin - - - -

3.9 alpine (musl) python-magic wheel - - 17.3M

3.9 alpine (musl) python-magic - - - -

3.9 alpine (musl) python-magic-bin build_error - - - -

3.9 alpine (musl) python-magic-bin - - - -

3.9 slim (glibc) python-magic wheel 1.7s - 18M

3.9 slim (glibc) python-magic - - - -

3.9 slim (glibc) python-magic-bin build_error - 1.6s - -

3.9 slim (glibc) python-magic-bin - - - -

Imports

magic
wrong
```
from libmagic import Magic
```
correct
```
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 last tested: 2026-04-24

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}")