From 64a9033539d4f27f28bf19d4c920fbba3d863f33 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 5 Feb 2026 06:54:09 -0800
Subject: [PATCH] Disable torchcodec in transformers when FFmpeg is missing
 (#3989)

* Disable torchcodec in transformers when FFmpeg is missing

When torchcodec is installed but FFmpeg libraries are unavailable,
transformers still thinks torchcodec is available (via find_spec check)
and tries to use it for audio loading, causing RuntimeError.

This adds disable_torchcodec_if_broken() which tests if torchcodec can
actually load its native libraries, and if not, patches transformers'
_torchcodec_available to False so it falls back to librosa instead.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Daniel Han <danielhanchen@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/__init__.py     |  3 +++
 unsloth/import_fixes.py | 29 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index fad37a786d..4357ad63aa 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -139,6 +139,7 @@ from .import_fixes import (
     fix_executorch,
     patch_vllm_for_notebooks,
     patch_torchcodec_audio_decoder,
+    disable_torchcodec_if_broken,
 )
 
 fix_xformers_performance_issue()
@@ -158,6 +159,7 @@ patch_openspiel_env_async()
 fix_executorch()
 patch_vllm_for_notebooks()
 patch_torchcodec_audio_decoder()
+disable_torchcodec_if_broken()
 
 del fix_xformers_performance_issue
 del fix_vllm_aimv2_issue
@@ -175,6 +177,7 @@ del patch_openspiel_env_async
 del fix_executorch
 del patch_vllm_for_notebooks
 del patch_torchcodec_audio_decoder
+del disable_torchcodec_if_broken
 
 # Torch 2.4 has including_emulation
 if DEVICE_TYPE == "cuda":
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 3def7e7e8b..97e74dfb57 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1053,3 +1053,32 @@ def patch_torchcodec_audio_decoder():
         _patch()
     except (ImportError, AttributeError, RuntimeError):
         pass
+
+
+def disable_torchcodec_if_broken():
+    """Disable torchcodec in transformers if it cannot actually load.
+
+    transformers checks if torchcodec is installed via importlib.util.find_spec(),
+    but this returns True even when torchcodec cannot load its native libraries
+    (e.g., when FFmpeg is missing). This causes runtime errors when transformers
+    tries to use torchcodec for audio loading.
+
+    This function tests if torchcodec can actually load and if not, patches
+    transformers to think torchcodec is unavailable so it falls back to librosa.
+    """
+    try:
+        import importlib.util
+
+        if importlib.util.find_spec("torchcodec") is None:
+            return  # torchcodec not installed, nothing to do
+
+        # Test if torchcodec can actually load
+        from torchcodec.decoders import AudioDecoder
+    except (ImportError, RuntimeError, OSError):
+        # torchcodec cannot load - disable it in transformers
+        try:
+            import transformers.utils.import_utils as tf_import_utils
+
+            tf_import_utils._torchcodec_available = False
+        except (ImportError, AttributeError):
+            pass