Repository navigation
Add notes to ImportError for common issues #127598
Description
Feature or enhancement
Proposal:
ImportErrors are very common, and almost always dependent on the interpreter initialization and/or environment setup. There are many common issues we could try to detect, and give users hints on the possible cause.
- Failing to load native modules when a module for a different ABI is available
- Eg. Environment colision between regular and free-threaded builds when using the Windows installer #127294 (comment)
- A
.cp313t-win_amd64.pydmodule is available, but we were looking for.cp313-win_amd64.pyd
- A
- Eg. Environment colision between regular and free-threaded builds when using the Windows installer #127294 (comment)
- Failing to import a non-stdlib module with the
siteinitialization disabled (-S) - Failing to import a module available in the user site-packages with the user
siteinitialization disabled (-s) - Failing to import a module available in
.withPYTHONSAFEPATH/-Penabled - Failing to import a module when ignoring
PYTHON*environment variables (-E) butPYTHONPATHorPYTHONHOMEare set (which users might be relying on) - (suggest more!)
Has this already been discussed elsewhere?
No response given
Links to previous discussion of this feature:
No response
Activity
ZeroIntensity commentedon Dec 4, 2024
Related: #125873
MonadChains commentedon Jul 19, 2025
Hi @FFY00 and @ZeroIntensity I open a mr to add some flavour text for this case:
gh-127598: Improve ModuleNotFoundError when -S is passed (GH-136821)
MonadChains commentedon Jul 24, 2025
I was also thinking to add the message for the cases where:
however, I'm not sure how to handle such cases, since these are options think mainly for safety reasons, is it safe to traverse the removed path on the traceback when such the
ImportErrorhappens?pythongh-127598: Improve ModuleNotFoundError when -S is passed (pytho…
pythongh-127598: Improve ModuleNotFoundError when -S is passed (pytho…