Whenever you try to import a module, as in:
import module
Python searches for the module in a systematic manner. This is known as the module search path or import path. The module is searched in the following locations in the given order:
- The current working directory where the program is being executed.
PYTHONPATH
: This is an environment variable that contains a list of directories where Python should look for modules.- The standard library. If the module is not found in the current directory or
PYTHONPATH
, the standard library is searched. - The
site-packages
directory: This is a directory where third-party modules are installed. Python searches this directory if the module is not found in the previous locations. - Any other directories specified in the
sys.path
variable
If the module is not found in any of the above locations, Python will raise a ModuleNotFoundError
exception.
When the module is found in any of the above paths, the search is terminated. This means that if for example you have a file named math.py
in your working directory the search for import math
will stop at that file, even if there is another module named math
in the standard library. This is one reason why your files should not have same names as standard library modules, to avoid conflicts in the import process.
The paths specified by PYTHONPATH
environment variable will take precedence over the standard library paths.
The sys.path list
The sys.path
variable maintains a list of paths in the order that they will be searched by the import system.
On windows
import sys #import the sys module
for p in sys.path:
print(p)
C:\Users\John\Desktop
C:\Python312\python312.zip
C:\Python312\DLLs
C:\Python312\Lib
C:\Python312
C:\Python312\Lib\site-packages
on linux
import sys #import the sys module
for p in sys.path:
print(p)
When the interpreter is looking for a module or package, it will search through the paths in order until it finds the desired file.
Update Search directories
The most obvious way to ensure that a module will always be found by the interpreter is to place it at the directory where the program is being executed.
In some cases, however, you may want the import system to search for a module in a directory other than the default ones. There are two ways to achieve this:
- Append the directory to the
sys.path
list. - Update the
PYTHONPATH
environment variable to include the directory.
Append the the directory to sys.path
This is the most basic way to add a new directory to the search path. You simply need to append the path to the directory where the module exists to the sys.path
variable.
import sys
sys.path.append('path/to/modules')
This ensures that the interpreter searches the given directory if the module is not found in all the preceding directories in the hierarchy.
Note that this will only affect the current running program it will not take effect systemwide.
You can also remove a directory from sys.path
if you don't want the interpreter to search that directory.
import sys
sys.path.remove('directory/to/remove/')
Update the PYTHONPATH
envrionment variable
Doing this will take effect globally. It is therefore not advisable unless you want the module to be available systemwide.
The way to update environment variables depends on the operating system your computer is running.