file-magic

What it is and what it does

file-magic is a ctypes wrapper around the libmagic library, which is the same engine used by the Unix `file` command. It lets you identify what a file actually is—its MIME type, character encoding, and human-readable type name—by examining its content or path, rather than relying on file extensions.

The package has no Python runtime dependencies and installs as a pure wheel, making it lightweight to add to any project. It works by calling into the native libmagic library, so you need libmagic available on your system (usually pre-installed on Linux/macOS, or installable via package manager). The API is straightforward: pass a filename to `detect_from_filename()` and get back an object with `mime_type`, `encoding`, and `name` attributes.

Use it for:

• Validate uploaded files in web applications by checking actual MIME type instead of trusting user-supplied extensions.
• Automatically categorize files in batch processing pipelines based on detected type and encoding.
• Build file management tools that need to identify file types for sorting, filtering, or routing decisions.
• Detect character encoding of text files to handle them correctly during import or conversion workflows.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

file-magic provides a Python interface to libmagic, enabling detection of file types, MIME types, and encodings from file paths or content.

Yes. file-magic is a stable, low-friction wrapper around a well-established system library. It has no Python dependencies, installs cleanly, carries a permissive license, and solves a real problem—reliable file type detection—that's otherwise tedious to implement. The main gotcha is the libmagic system dependency, which is typically already present but must be verified in your deployment environment.

Install

file-magic on PyPI

pip install file-magic

uv add file-magic

poetry add file-magic

Installing file-magic

Before you install

Low install friction; pure Python wheel with no runtime dependencies. Repository is active with recent commits and moderate GitHub engagement (1647 stars).

License in practice

Permissive BSD-style license (copyright Ian F. Darwin and contributors) allows commercial and private use with minimal restrictions—attribution and disclaimer retention required.

Quickstart

import magic

detected = magic.detect_from_filename('example.txt')
print(detected.mime_type)
print(detected.encoding)
print(detected.name)

Requires libmagic system library to be installed on the host system (typically available via system package manager).

Verify before relying

• Whether libmagic is pre-installed on common deployment targets or must be added as a system dependency.
• Performance characteristics when analyzing large files or high-throughput scenarios.

Package facts

Evidence: file_magic-0.4.1-py3-none-any.whl

Keywords: file, magic

Tags

More Utilities packages