transformers - 💡(How to fix) Fix Provide HF_USE_MLX=0 / public flag to disable MLX backend detection at import time

Summary

Transformers' import-utils module probes for MLX availability during its own load and imports mlx.core for backend type checks if mlx is installed. There is no documented opt-out. On some Apple Silicon configurations, import mlx.core aborts the interpreter (silent SIGABRT during native init), taking the whole host process down before user code can react.

Context

The current backend-detection code path (paraphrased from transformers/utils/import_utils.py):

_mlx_available = importlib.util.find_spec("mlx") is not None
# … later …
if _mlx_available:
    import mlx.core  # type-check probe — can abort interpreter

USE_TF=0 and USE_TORCH=0 exist as opt-outs for those backends, but no equivalent for MLX. Setting HF_USE_MLX=0 (or any equivalent public knob) would let downstream projects that explicitly do not use MLX prevent the import probe entirely.

Why a public flag matters here

Some downstream projects target Apple Silicon but use PyTorch (eager-mode MPS) exclusively, with mlx/mlx.core installed only as a transitive dependency or development-time artefact. On those hosts, the mlx.core import probe is pure cost and can be unsafe; today the only options are:

1. Uninstall mlx — not always feasible (transitive deps).
2. Patch Transformers internals — what we currently do, against our own no-library-patches rule. Brittle on every Transformers upgrade.
3. Wrap every Transformers import in a sandboxed subprocess — extreme.

A documented HF_USE_MLX=0 (or transformers.utils.disable_backend("mlx")) collapses all three into one line.

Proposed change

Mirror the existing USE_TORCH / USE_TF shape:

_mlx_available = (
    os.environ.get("HF_USE_MLX", "AUTO").upper() != "0"
    and importlib.util.find_spec("mlx") is not None
)

with documentation in the env-var reference page.

Workaround in use today

A MetaPathFinder installed before any Transformers import that:

1. Blocks mlx.core imports (raises ModuleNotFoundError).
2. Wraps the Transformers import_utils loader and writes module._mlx_available = False after exec.

Source: [docling-project link to import_safety.py and ADR 0003 — fill in after publishing this issue].

Acceptance criteria for closing this on our side

1. Transformers ships an env var or public flag to disable MLX detection.
2. The flag is documented.
3. We can drop our MetaPathFinder and use the flag.