sec05 - Chapter 3: Understanding Python’s Module Search Process: sys.path and sys.modules Explained

In this lecture, you will learn how Python locates modules when executing an import statement. When Python looks for modules, it follows a predefined “search list” (search path) in a specific order.

You can inspect this “search list” using the path variable in the sys module. Understanding this makes it easier to determine what to fix when you encounter import-related errors such as ModuleNotFoundError.

What Is the Module Search Order? How Python’s import Mechanism Works

When Python executes an import statement, it first checks whether the module information is already cached in sys.modules.

If the module is not found in sys.modules, Python searches for it in the following order:

• ① It first checks the folder of the currently running script.
• ② It then checks the directories listed in the PYTHONPATH environment variable.
• ③ Next, it searches the Python standard library (lib folder).
• ④ Finally, it looks in the third-party packages installed by pip (site-packages).

This order is fixed, and Python loads the first matching module it finds. Therefore, if modules with the same name exist in multiple locations, Python may import a module you did not intend to use.

How to Check the Module Search Path Using sys.path

Let’s start by examining the contents of sys.path. sys.path is a list that stores the directories Python searches when looking for modules.

Create a new file and run the following code to inspect it. (The output varies depending on your OS, Python installation location, and the folder from which you run the script.)

import sys
from pprint import pprint

pprint(sys.path)

# Example output (varies by environment)
['C:\\Users\\xxx\\Documents\\python101',  # Folder of the running script (first in sys.path)
 'C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python313\\python313.zip',
 'C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python313\\DLLs',
 'C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python313\\Lib',  # Standard library
 'C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python313',
 'C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\site-packages']  # Third-party packages installed by pip

This list represents the exact order in which Python searches for modules. It goes through each directory from top to bottom, stopping as soon as it finds a matching file.

The first entry in the output is the folder containing the currently executing script. After that, the list contains (if configured) the folders from PYTHONPATH, then the standard library, and finally the directory where libraries installed via pip install are stored (site-packages).

How to Temporarily Add a Search Path (sys.path.append)

To temporarily add a search path, simply append a new element to the sys.path list. Note that this setting is temporary and will be reset when Python restarts.

import sys
sys.path.append(r'C:\Users\xxx\Documents\python101\fortune_cookie')

import fortune

If you want to import fortune from another module (and the path up to fortune_cookie/ is not in sys.path), you can add the path as shown above to make the fortune module importable.

Summary: Understanding the Search Path Makes import Errors Less Intimidating

• Python searches the folders in sys.path from top to bottom.
• You can temporarily add search paths using sys.path.append().
• By understanding the relationship between your execution location and package structure, you can more easily troubleshoot import errors.