sec05 - Appendix 2：How to Prevent Module Name Conflicts in Python: Avoiding Collisions with Standard Library Modules

What Happens When Python Module Names Conflict

As you learn Python, you gradually begin using “external modules” and “libraries.” These tools make it easy to accomplish things that cannot be done with standard functionality alone. However, there is an important point you must be careful about: module name and function name conflicts (naming conflicts).

In Python, using the same name unintentionally can lead to unexpected bugs.

For example, Python provides the standard library random module, which is widely used when working with random numbers. But if you create your own file named random.py, how will Python treat the standard library random and your custom random? Let’s take a look.

A Concrete Example of Naming Conflicts in Python

Consider the following project structure:

project/
├─ random.py
└─ main.py

Now let’s write the following code inside the custom random.py:

# random.py (custom file)
def hello():
    print('This is the custom random module')

Next, try using random inside main.py.

# main.py
import random

print(random)
print(random.randint(1, 10))  # Function from the standard library
print(random.hello())  # Function from the custom module

Behavior of Module Conflicts in VSCode

Now, what happens when this code is executed in Visual Studio Code? The result is that the standard library version of random is loaded. As shown below, the path indicates that Python is referencing the standard library. The random.randint() function from the standard random module executes successfully. Since the custom random is not loaded, attempting to execute random.hello() (from the custom module) results in an AttributeError.

<module 'random' from 'C:\Users\xxx\AppData\Local\Programs\Python\Python313\Lib\random.py'>
4  # <- Value varies because it is random.

AttributeError: module 'random' has no attribute 'hello'

Import Behavior on the Command Line

While Visual Studio Code loads the standard library version of random first, the command-line behavior is different.

To run a Python file from the command line, first navigate to the current directory using the cd command (adjust the path to match your environment).

cd C:\Users\xxx\Documents\python101\project

Then run main.py using the python command:

python main.py

The output looks like this:

<module 'random' from 'C:\\Users\\xxx\\Documents\\python101\\project\\random.py'>
Traceback (most recent call last):
  File "C:\Users\xxx\Documents\python101\project\main.py", line 5, in <module>
    print(random.randint(1, 10))  # Function from the standard library
          ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint'
(consider renaming 'C:\Users\xxx\Documents\python101\project\random.py' since
it has the same name as the standard library module named 'random'
and prevents importing that standard library module)

This output shows that the module being referenced is the custom random module. Since the custom module does not contain the randint() function, an error is raised.

If you comment out line 5 in main.py (print(random.randint(1, 10))), the script will run without errors.

How Python’s Import Process and Module Search Path Work

Command-Line Behavior (Explaining Search Order via sys.path)

Python determines the order in which it searches for modules using a list called the “module search path” (sys.path). The first element in this list is the directory containing the currently executing script (the current directory). Based on this rule, Python imports your custom random.py first.

import sys
from pprint import pprint

pprint(sys.path)

Since Python follows this search-path rule, the command-line behavior is considered correct.

Differences in Import Priority Caused by the VSCode Debugger

So why does Visual Studio Code prioritize the standard library version of random even though it should normally be loaded later?

The reason is that Python stores loaded modules in a dict called sys.modules. When a module is imported inside main.py, Python checks whether a module with the same name already exists in sys.modules. If it does, Python does not search for the module again and instead reuses the already registered module.

When main.py is executed through Visual Studio Code, the standard library modules—which should normally have lower priority—are loaded before your project’s modules. This causes the standard library random to be registered in sys.modules before import random in main.py is evaluated, preventing the custom random module from being imported. (This behavior varies depending on VSCode’s debugger configuration.)

The important takeaway is that the referenced module can change depending on the execution environment.

Practical Measures to Avoid Module Name Conflicts

Some standard library modules may be prioritized differently depending on the execution environment (such as random), while others are core modules that always take priority (such as sys and os). To prevent issues in all cases, the following measures are recommended:

• Avoid naming files after standard library or built-in modules
  • Avoid names such as random.py, sys.py, os.py, json.py, etc.
  • If you must use a word like “random” in a module name, change it to something like “random_tools” to avoid conflicts.
• Organize modules into folders (use package namespaces)
  • Create random.py inside a custom package hierarchy, such as import rand.random or import utility.random, so that it can be distinguished from the standard library at import time.
  • When creating a package, avoid naming the folder itself random, as that would cause the same naming conflict. Use names like rand or utility instead.

Summary of Python Module Name Conflicts

• Creating files with the same name as standard library or built-in modules can cause unexpected errors.
• Choose module names carefully to avoid unnecessary naming conflicts.