From 0219ab7a3856597dc5fe3eaba02854468ccfb687 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= <lains@riseup.net>
Date: Thu, 19 Feb 2026 17:49:12 +0000
Subject: [PATCH] GH-145006: add ModuleNotFoundError hints when a module for a
 different ABI exists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns <lains@riseup.net>
---
 Lib/test/test_traceback.py                    | 11 +++++++
 Lib/traceback.py                              | 31 +++++++++++++++++++
 ...-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst |  2 ++
 3 files changed, 44 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Library/2026-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst

diff --git a/Lib/test/test_traceback.py b/Lib/test/test_traceback.py
index 99ac7fd83d91cb..3c8d3bae69ffde 100644
--- a/Lib/test/test_traceback.py
+++ b/Lib/test/test_traceback.py
@@ -13,6 +13,7 @@
 import tempfile
 import random
 import string
+import importlib.machinery
 from test import support
 import shutil
 from test.support import (Error, captured_output, cpython_only, ALWAYS_EQ,
@@ -5194,6 +5195,16 @@ def test_windows_only_module_error(self):
         else:
             self.fail("ModuleNotFoundError was not raised")
 
+    def test_find_incompatible_extension_modules(self):
+        """_find_incompatible_extension_modules assumes the last extension in
+        importlib.machinery.EXTENSION_SUFFIXES (defined in Python/dynload_*.c)
+        is untagged (eg. .so, .pyd).
+
+        This test exists to make sure that assumption is correct.
+        """
+        if importlib.machinery.EXTENSION_SUFFIXES:
+            self.assertEqual(len(importlib.machinery.EXTENSION_SUFFIXES[-1].split('.')), 2)
+
 
 class TestColorizedTraceback(unittest.TestCase):
     maxDiff = None
diff --git a/Lib/traceback.py b/Lib/traceback.py
index b16cd8646e43f1..4b0acb4bafca4b 100644
--- a/Lib/traceback.py
+++ b/Lib/traceback.py
@@ -3,6 +3,7 @@
 import collections.abc
 import itertools
 import linecache
+import os
 import sys
 import textwrap
 import types
@@ -1129,6 +1130,11 @@ def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
                 self._str += (". Site initialization is disabled, did you forget to "
                     + "add the site-packages directory to sys.path "
                     + "or to enable your virtual environment?")
+            elif abi_tag := _find_incompatible_extension_module(module_name):
+                self._str += (
+                    ". Although a module with this name was found for a "
+                    f"different Python version ({abi_tag})."
+                )
             else:
                 suggestion = _compute_suggestion_error(exc_value, exc_traceback, module_name)
                 if suggestion:
@@ -1880,3 +1886,28 @@ def _levenshtein_distance(a, b, max_cost):
             # Everything in this row is too big, so bail early.
             return max_cost + 1
     return result
+
+
+def _find_incompatible_extension_module(module_name):
+    import importlib.machinery
+    import importlib.resources.readers
+
+    if not module_name or not importlib.machinery.EXTENSION_SUFFIXES:
+        return
+
+    # We assume the last extension is untagged (eg. .so, .pyd)!
+    # tests.test_traceback.MiscTest.test_find_incompatible_extension_modules
+    # tests that assumption.
+    untagged_suffix = importlib.machinery.EXTENSION_SUFFIXES[-1]
+
+    parent, _, child = module_name.rpartition('.')
+    if parent:
+        traversable = importlib.resources.files(parent)
+    else:
+        traversable = importlib.resources.readers.MultiplexedPath(
+            *filter(os.path.isdir, sys.path)
+        )
+
+    for entry in traversable.iterdir():
+        if entry.name.startswith(child + '.') and entry.name.endswith(untagged_suffix):
+            return entry.name.removeprefix(child + '.').removesuffix(untagged_suffix)
diff --git a/Misc/NEWS.d/next/Library/2026-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst b/Misc/NEWS.d/next/Library/2026-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst
new file mode 100644
index 00000000000000..69052c7ca92c8a
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst
@@ -0,0 +1,2 @@
+Add :exc:`ModuleNotFoundError` hints when a module for a different ABI
+exists.