Skip to content

Getting Started

This tutorial takes you from installation to the first successful file type detection.

Installation

Using pip

pip install filetype-detector

Using rye

If you're using rye for dependency management:

rye sync

Interactive terminal demo

Browse any directory with a live filename filter and side-by-side strategy results:

filetype-detector-demo path/to/files

python -m filetype_detector path/to/files launches the same interface. Omit the directory to browse the current working directory.

System Requirements

Python

  • Python >= 3.10

System Libraries

Important: MagicInferencer and HybridInferencer require the libmagic system library. Install it based on your operating system:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install libmagic1

Fedora/RHEL/CentOS

sudo dnf install file-libs
# or for older versions:
# sudo yum install file-libs

Arch Linux

sudo pacman -S file

macOS

Using Homebrew (Recommended): 

brew install libmagic

Using MacPorts: 

sudo port install file

Windows

Windows doesn't have native libmagic support. Use python-magic-bin:

pip install python-magic-bin

Alternatively, download the libmagic DLL manually from: - file.exe Windows releases

Alpine Linux (Common in Docker)

apk add --no-cache file

Verify Installation

After installation, verify libmagic is available:

file --version

You should see output like: file-5.x

If this command works, libmagic is properly installed and MagicInferencer will work correctly.

Basic Usage

For most use cases, start with AutoInferencer(backend="hybrid") - it provides a single entry point with the same balanced behavior as HybridInferencer:

Content-based backends require the supplied path to reference an existing file.

from filetype_detector import AutoInferencer

inferencer = AutoInferencer(backend="hybrid")
file_type = inferencer.infer("document.pdf")
'.pdf' in file_type.extensions  # True

Using Individual Inferencers

You can also use inferencer classes directly:

from filetype_detector import MagicInferencer

inferencer = MagicInferencer()
file_type = inferencer.infer("document.pdf")
print(file_type.extensions)  # Output: ('.pdf',)

Using AutoInferencer

For type-safe backend selection, use AutoInferencer:

from filetype_detector import AutoInferencer

magic = AutoInferencer(backend="magic")
file_type = magic.infer("file_without_ext")
print(file_type.extensions)

See Examples and Patterns for longer examples and AutoInferencer for backend selection details.

Next Steps