Filetype Inference Library

1.2.0 verified Tue May 12 auth: no python install: verified

Small and dependency-free Python package to infer file type and MIME type by checking the magic numbers signature of a file or buffer. It is a Python port from the 'filetype' Go package, offering a simple and friendly API for a wide range of file types. Currently at version 1.2.0, it is actively maintained with periodic updates.

pip install filetype

Common errors

error ModuleNotFoundError: No module named 'filetype' ↓

cause The 'filetype' package is not installed in your Python environment.

fix

You need to install the package using pip: pip install filetype

error filetype.guess() returns None ↓

cause The 'filetype' library could not infer the file type from its magic numbers. This often happens if the file is corrupted, empty, or its type is not supported by the library (version 1.2.0).

fix

Ensure the file is valid and supported. If reading from a buffer, ensure enough bytes are provided. Handle the None return gracefully:

import filetype

kind = filetype.guess('path/to/your/file')
if kind is None:
    print('File type could not be determined or is not supported.')
else:
    print(f'File extension: {kind.extension}')
    print(f'File MIME type: {kind.mime}')

error FileNotFoundError: [Errno 2] No such file or directory: 'your_file_name' ↓

cause The specified file path for `filetype.guess()` or file operations does not point to an existing file.

fix

Verify that the file path is correct and that the file exists at the given location. Use an absolute path or ensure the script is run from the correct directory.

import filetype
import os

file_path = 'path/to/correct/file.jpg'
if os.path.exists(file_path):
    kind = filetype.guess(file_path)
    if kind:
        print(f'Detected type: {kind.mime}')
    else:
        print('File type not recognized.')
else:
    print(f'Error: File not found at {file_path}')

Warnings

gotcha The `filetype.guess()` function returns `None` if it cannot determine the type of the given file or buffer. Always check for `None` before accessing `extension` or `mime` attributes. ↓

fix Implement a check for `if kind is None:` or similar logic to handle unknown file types gracefully.

gotcha `filetype.guess()` will raise a `FileNotFoundError` if the provided file path does not exist. Ensure the file path is correct and the file is accessible. ↓

fix Use `try-except FileNotFoundError` blocks to handle missing files, or verify file existence using `os.path.exists()` before calling `guess()`.

gotcha When guessing from a buffer, `filetype` typically only requires the first 261 bytes (maximum file header size) for accurate detection. Providing an insufficient number of bytes may lead to incorrect type inference or `None` being returned. ↓

fix Ensure that the buffer passed to `filetype.guess()` contains at least the initial bytes of the file, ideally up to 261 bytes, for reliable type detection.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.02s 18.0M

3.10 alpine (musl) - - 0.02s 18.0M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.03s 19.9M

3.11 alpine (musl) - - 0.03s 19.9M

3.11 slim (glibc) wheel 1.6s 0.02s 20M

3.11 slim (glibc) - - 0.02s 20M

3.12 alpine (musl) wheel - 0.03s 11.7M

3.12 alpine (musl) - - 0.03s 11.7M

3.12 slim (glibc) wheel 1.4s 0.03s 12M

3.12 slim (glibc) - - 0.03s 12M

3.13 alpine (musl) wheel - 0.02s 11.5M

3.13 alpine (musl) - - 0.02s 11.4M

3.13 slim (glibc) wheel 1.5s 0.02s 12M

3.13 slim (glibc) - - 0.02s 12M

3.9 alpine (musl) wheel - 0.02s 17.5M

3.9 alpine (musl) - - 0.02s 17.5M

3.9 slim (glibc) wheel 1.8s 0.02s 18M

3.9 slim (glibc) - - 0.02s 18M

Imports

filetype
```
import filetype
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to use `filetype.guess()` to infer the type of a file based on its path and from a bytes buffer. It creates a dummy JPEG file to showcase the functionality and then cleans it up. The library returns a `Kind` object with `extension` and `mime` attributes, or `None` if the type cannot be determined.

import filetype
import os

# Create a dummy JPEG file for demonstration
dummy_jpeg_path = 'dummy.jpg'
# A minimal JPEG header (first few bytes of a typical JPEG file)
# In a real scenario, you'd read from an actual file.
jpeg_magic_bytes = b'\xFF\xD8\xFF\xE0\x00\x10\x4A\x46\x49\x46\x00\x01'

try:
    with open(dummy_jpeg_path, 'wb') as f:
        f.write(jpeg_magic_bytes)

    # Guess the file type from the path
    kind = filetype.guess(dummy_jpeg_path)

    if kind is None:
        print('Cannot guess file type!')
    else:
        print(f'File extension: {kind.extension}')
        print(f'File MIME type: {kind.mime}')

    # You can also guess from a buffer/bytes object
    kind_from_buffer = filetype.guess(jpeg_magic_bytes)
    if kind_from_buffer:
        print(f'Buffer extension: {kind_from_buffer.extension}')
        print(f'Buffer MIME type: {kind_from_buffer.mime}')

finally:
    # Clean up the dummy file
    if os.path.exists(dummy_jpeg_path):
        os.remove(dummy_jpeg_path)