---
id: file-magic
version: "0.4.1"
license: Copyright (c) Ian F. Darwin 1986-1995. Software written by Ian F. Darwin and others; maintained 1995-present by Christos Zoulas and others. Redistribution and use in source and binary forms, with or… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# file-magic — Python front end for libmagic(3)

License: permissive · Maintenance: active · Downloads: 84.6K/mo

## 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 above — 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

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

- License: Copyright (c) Ian F. Darwin 1986-1995. Software written by Ian F. Darwin and others; maintained 1995-present by Christos Zoulas and others. Redistribution and use in source and binary forms, with or… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 84.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

file type detection python, mime type detection, libmagic python bindings, file magic detection, detect file encoding, file-type-detection, ctypes-binding

[View on SkillFed](https://skillfed.io/packages/file-magic) · [View on PyPI](https://pypi.org/project/file-magic/)