Repository navigation
Add more specific error message when file has same name as an imported module #95754
Description
Feature / enhancement
Currently, if a python file I create and am trying to run has the same name as a module I'm importing in it (i.e. my file is named random.py and I try to do import random; print(random.randint(5)), the following error message appears:
AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)
Instead, for this particular scenario, a more specific error message would be helpful:
ImportError: random.py imported itself. File name should be different than the imported module name.
Pitch
Frequently, someone learning python will try to name their python files after the topic they are learning about. These topics can be about a specific module (e.g. random, turtle, pygame, requests). For instance, someone experimenting with the turtle module, might name their python file turtle.py. This results in the scenario of a person trying to import a module, but instead their program tries to import itself because of the name collision.
The current error message isn't clear that the issue is the filename conflicting with the module name and overriding it. Folks with more experience can deduce that from the "circular import" portion, but beginners are often confused by the "AttributeError" portion. I think this scenario would be a good candidate for a more specific error message, to better warn about this common pitfall.
The recent improvements for more detailed and specific error messages have helped many people, especially those new to Python. I think this would be a worthwhile addition in that same vein.
Considerations & discussion points
The example improved error message I have above is very much open to improvements, if folks have suggestions.
I am also operating under the somewhat informed assumption that there isn't a valid case for a file to import itself, so there would not be an issue with this error appearing if the imported module is the same name as the file itself.
Activity
Kinza-Raza commentedon Aug 8, 2022
Hi @janine9vn 👋🏼
What version are you using? I tried this on version 3.9.13 and getting a slightly different phrased error
I agree, ImportError class would be better suited. Perhaps a better error message could be:
Open to suggestions, would love to take this up once finalised!
carljm commentedon Dec 1, 2023
Thanks for opening this issue! I agree that we could likely make some changes to make this common situation easier to debug, especially for people new to Python.
I don't think that we should change the exception type from
AttributeErrortoImportError. The actual error that occurs in this case is anAttributeError(because of trying to access therandintattribute on a module that doesn't have it); even though the root cause here is import-related, changing the exception type obscures what actually happened, makes Python less consistent, and will make it harder to gain an understanding of how the import system actually works.Fortunately, I think the exception type is not the most important thing here; I think we improve debuggability much more by changing the exception message itself. One simple change that I think would be worthwhile would be to add the file path to the module to the error message, so it would be more obvious that the
randommodule being used is the one the developer created, not the stdlib one. So the error could look something likeThere's more that we could consider, but I think even this much would be a pretty good start.
pythongh-95754: Better AttributeError on partially initialised module
vstinner commentedon Dec 1, 2023
Consider using
-Pcommand line option to not add the path to the executed script to sys.path: https://docs.python.org/dev/using/cmdline.html#cmdoption-P It allows running a customrandom.pyscript which imports successfullyrandomstandard library module (import random).ericsnowcurrently commentedon Dec 1, 2023
FWIW, this reminded me of PEP 338, PEP 366, and one other proposal @ncoghlan had that outlined, IIRC, 4 things that needed fixing (I don't remember if it was a PEP or tracker issue).
gh-95754: Better AttributeError on partially initialised module (#112577
hauntsaninja commentedon Dec 21, 2023
We've implemented carljm's suggestion. Are there any other concrete suggestions on how to improve the error? We could try special casing standard library here and provide a different error message if the module name is in
sys.stdlib_module_names?pythongh-95754: Better AttributeError on partially initialised module (…
pythongh-95754: Better AttributeError on partially initialised module (…
pythongh-95754: Better AttributeError on partially initialised module (…
gh-95754: Better error when script shadows a standard library or thir…
hauntsaninja commentedon Apr 23, 2024
Okay, I implemented a more thorough set of new error messages in #113769
pythongh-95754: Better AttributeError on partially initialised module (…
taylor7936 commentedon Sep 29, 2025