# How to Use a Custom Model Directory with Magika: Complete Implementation Guide

> Learn how to use a custom model directory with Magika using the Python API, CLI, or environment variable. Implement Magika with your own models today.

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

---

**Yes, Magika supports custom model directories through the Python API constructor, CLI `--model-dir` flag, or the `MAGIKA_MODEL_DIR` environment variable.**

The Magika file identification library from Google's open-source repository provides flexible model loading capabilities. Whether you are deploying fine-tuned models or testing experimental weights, you can override the bundled default by pointing the library to any compatible directory containing the required ONNX artifacts.

## How Custom Model Support Works

Magika implements custom model loading through a cascading fallback system that prioritizes explicit arguments over environment variables and bundled defaults.

### The Magika Constructor

In [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) lines **86‑94**, the `__init__` method signature accepts an optional `model_dir` parameter:

```python
Magika(model_dir: Optional[Path] = None, …)

```

If you supply a `Path` object, the instance stores it internally in `_model_dir`. When omitted, Magika automatically resolves to the bundled default model located at `magika/models/<default-name>` alongside the source code.

### Validation Requirements

Before loading, Magika validates the directory structure in lines **97‑102** of [`magika.py`](https://github.com/google/magika/blob/main/magika.py). The library verifies that the path exists and contains both required files. If validation fails, Magika raises a `MagikaError` immediately, preventing runtime failures during inference.

### CLI and Environment Variable Fallbacks

The command-line interface in [`python/src/magika/cli/magika_client.py`](https://github.com/google/magika/blob/main/python/src/magika/cli/magika_client.py) lines **27‑33** exposes a `--model-dir` option that passes directly to the constructor. If you omit the flag, Magika checks the `MAGIKA_MODEL_DIR` environment variable before falling back to the default model.

## Required Files in a Custom Model Directory

A valid custom model directory must contain exactly two files:

- **`model.onnx`** – The ONNX-encoded neural network containing trained weights and architecture.
- **[`config.min.json`](https://github.com/google/magika/blob/main/config.min.json)** – Minimal configuration specifying input window sizes, confidence thresholds, and the label-to-content-type mapping.

The directory layout mirrors the bundled models structure:

```

my-custom-model/
├── model.onnx
└── config.min.json

```

Both files are generated when you export a trained Magika model using the training pipeline tools.

## Implementation Examples

### Python API with Explicit Path

Pass the directory path directly to the constructor when instantiating the `Magika` class:

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

# Path to directory containing model.onnx + config.min.json

custom_dir = Path("/home/user/custom_magika_model")

# Initialize with custom model

magika = Magika(model_dir=custom_dir)

# Identify file content type

result = magika.identify_path("example.pdf")
print(result.prediction.output.label)   # ContentTypeLabel.PDF or custom label

```

### Command-Line Interface

Use the `--model-dir` flag to override the default model for CLI operations:

```bash
magika --model-dir /home/user/custom_magika_model myfile.bin

```

### Environment Variable Configuration

Set `MAGIKA_MODEL_DIR` to avoid hardcoding paths in scripts or shell commands:

```bash
export MAGIKA_MODEL_DIR=/home/user/custom_magika_model
magika myfile.bin          # CLI automatically picks up the environment variable

```

For Python applications that rely on default initialization:

```python
import os
from magika import Magika

os.environ["MAGIKA_MODEL_DIR"] = "/home/user/custom_magika_model"
magika = Magika()          # No constructor argument needed

```

## Summary

- **Constructor parameter**: Pass `model_dir=Path("/your/path")` to `Magika()` in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py).
- **CLI flexibility**: Use `--model-dir` flag in [`magika_client.py`](https://github.com/google/magika/blob/main/magika_client.py) for command-line operations.
- **Environment fallback**: Set `MAGIKA_MODEL_DIR` when you want system-wide configuration without code changes.
- **Validation**: Both `model.onnx` and [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json) must exist in the target directory or `MagikaError` is raised.
- **Structure**: Custom directories must mirror the bundled model layout exactly.

## Frequently Asked Questions

### What files must a custom Magika model directory contain?

Every custom model directory must contain `model.onnx` (the neural network weights) and [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json) (metadata and thresholds). These files are generated during the model export process in the Magika training pipeline. Missing either file triggers a `MagikaError` during initialization.

### Can I use an environment variable instead of passing paths in code?

Yes. Set the `MAGIKA_MODEL_DIR` environment variable to your model directory path. When the `Magika` constructor is called without arguments, or when using the CLI without `--model-dir`, the library automatically checks this environment variable before falling back to the bundled default model.

### What happens if the model files are missing or corrupted?

Magika performs strict validation in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) lines 97‑102. If the directory does not exist, or if either `model.onnx` or [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json) is missing, the library raises a `MagikaError` with a descriptive message. This prevents silent failures and ensures clear debugging information.

### Does Magika support loading multiple custom models simultaneously?

No. Each `Magika` instance loads exactly one model directory specified at initialization. To use multiple models concurrently, instantiate separate `Magika` objects with different `model_dir` paths. Each instance maintains its own model session and configuration independently.