# How to Identify a File by Path with the Magika Python API

> Learn to identify files by path using the Magika Python API. Discover content type, confidence, and MIME type with a simple function call for accurate file analysis.

- Repository: [Google/magika](https://github.com/google/magika)
- Tags: how-to-guide
- Published: 2026-04-16

---

**Instantiate the `Magika` class and call `identify_path()` with a file system path to receive a `MagikaResult` object containing the detected content type, confidence score, and MIME type.**

The Magika Python API provides a robust interface for content type detection using machine learning models. Developed by Google and hosted at `google/magika`, this library is implemented primarily in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) and supports both single-file and batch identification workflows.

## Initializing the Magika Class

The API centers around the **`Magika`** class defined in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py). According to the source code at lines 57‑66, the constructor accepts optional configuration parameters to customize model behavior and output formatting.

You can specify the model directory, prediction mode, logging verbosity, and colorized output during instantiation. The `model_dir` parameter accepts a `Path` to a custom ONNX model, while `prediction_mode` controls confidence thresholds using the `PredictionMode` enum defined in [`python/src/magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/python/src/magika/types/prediction_mode.py).

## Identifying a Single File by Path

To identify a file’s content type, call **`identify_path`** with a file system path (string or `os.PathLike`). As implemented at lines 39‑48 of [`magika.py`](https://github.com/google/magika/blob/main/magika.py), this method validates the input argument, converts it to a `Path` object, and forwards the request to the internal processing pipeline.

Under the hood, `identify_path` delegates to `_get_result_from_path`, which opens the file, extracts a small set of byte-level features, and runs the ONNX inference model. For very small files that lack sufficient features, it falls back to lightweight heuristics rather than neural inference. The final result is produced via `_get_result_from_labels_and_score` and returned as a **`MagikaResult`** object (defined in [`python/src/magika/types/magika_result.py`](https://github.com/google/magika/blob/main/python/src/magika/types/magika_result.py)).

## Practical Code Examples

### Basic File Identification

```python
from magika import Magika

# Initialise with default model and high-confidence mode

magika = Magika()

# Identify the file at the given path

result = magika.identify_path("/path/to/your/file.png")

# Access the most useful fields

print("Detected label :", result.prediction.output.label)
print("Confidence     :", result.prediction.score)
print("MIME type      :", result.prediction.output.mime_type)

```

### Custom Model Configuration

```python
from pathlib import Path
from magika import Magika, PredictionMode

magika = Magika(
    model_dir=Path("/opt/magika/models/custom_v1"),
    prediction_mode=PredictionMode.BEST_GUESS,
    verbose=True,
    use_colors=True,
)

result = magika.identify_path(Path("example.pdf"))
print(result)          # Human-readable representation

print(result.to_dict())  # Full dictionary, handy for JSON output

```

### Batch Processing Multiple Files

For processing multiple files efficiently, use **`identify_paths`** (plural), which delegates each path to the same inference pipeline used by `identify_path`:

```python
from magika import Magika

files = [
    "doc1.docx",
    "image.jpg",
    "archive.zip",
]

magika = Magika()
batch_results = magika.identify_paths(files)

for res in batch_results:
    print(f"{res.path.name}: {res.prediction.output.label}")

```

## Key Implementation Files

The following source files comprise the public API and underlying inference pipeline:

- **[`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py)** — Contains the core `Magika` class, including `identify_path`, `identify_paths`, and the internal methods `_get_result_from_path` and `_get_result_from_labels_and_score`.

- **[`python/src/magika/types/magika_result.py`](https://github.com/google/magika/blob/main/python/src/magika/types/magika_result.py)** — Defines `MagikaResult`, `MagikaPrediction`, and related data structures returned by identification methods.

- **[`python/src/magika/types/content_type_label.py`](https://github.com/google/magika/blob/main/python/src/magika/types/content_type_label.py)** — Enum of supported content-type labels (e.g., `PNG`, `PDF`, `TXT`).

- **[`python/src/magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/python/src/magika/types/prediction_mode.py)** — Enum controlling confidence thresholds: `HIGH_CONFIDENCE`, `MEDIUM_CONFIDENCE`, and `BEST_GUESS`.

- **[`python/src/magika/logger.py`](https://github.com/google/magika/blob/main/python/src/magika/logger.py)** — Helper for coloured, level-aware logging used by the `Magika` class.

## Summary

- The **Magika Python API** centers on the `Magika` class in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py).
- Call **`identify_path()`** with a file path to obtain a `MagikaResult` containing the content type label, confidence score, and MIME type.
- Use **`identify_paths()`** for efficient batch processing of multiple files.
- Configure custom models, prediction modes, and logging via the constructor at lines 57‑66.

## Frequently Asked Questions

### What is the difference between identify_path and identify_paths?

**`identify_path`** processes a single file path and returns one `MagikaResult` object, while **`identify_paths`** accepts a list of paths and returns a list of results. Both methods use the same underlying ONNX model and feature extraction logic implemented in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py).

### What prediction modes are available in the Magika Python API?

The API supports three modes defined in [`python/src/magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/python/src/magika/types/prediction_mode.py): **`HIGH_CONFIDENCE`** (strict thresholds, fewer misclassifications), **`MEDIUM_CONFIDENCE`** (balanced approach), and **`BEST_GUESS`** (always returns the top prediction regardless of confidence).

### How does Magika handle very small files?

When `identify_path` delegates to `_get_result_from_path`, the implementation checks file size. For very small files that lack sufficient features for the ONNX model, Magika falls back to lightweight heuristics rather than neural inference, as implemented in the processing pipeline of [`magika.py`](https://github.com/google/magika/blob/main/magika.py).

### Can I use a custom model with the Magika Python API?

Yes. Pass a `Path` object to the `model_dir` parameter when constructing the `Magika` instance (lines 57‑66). This directs the API to load your custom ONNX model from the specified directory instead of the bundled default model.