Python's import mechanism locates files using a well-defined search path. When you use import to bring in a module, Python systematically searches through a series of directories to find the desired file.
The Import Search Path
The search path is determined by the sys.path list, which is a sequence of directories Python checks in order. Here's how it works:
- Current Directory: Python first looks in the directory where your script is located.
- Environment Variables: The
PYTHONPATHenvironment variable, if set, provides additional directories to search. - Standard Library Paths: Python includes a set of standard library directories that are automatically added to the search path.
- Site Packages: The
site-packagesdirectory, typically found within the Python installation, contains third-party modules.
Example
Imagine you have a script named my_script.py in a directory called my_project. You want to import a module called utils from a file utils.py located in the same directory. Here's how Python would find the file:
- Current Directory: Python starts by searching the directory where
my_script.pyresides. utils.pyFound: Sinceutils.pyis in the same directory, Python successfully locates it.
Practical Insights
- Explicit Path: If you know the exact location of a module, you can use the
sys.path.append()method to add it to the search path. - Package Structure: For larger projects, organize your code into packages by creating directories with an
__init__.pyfile. This helps Python find modules within the package structure. - Virtual Environments: Using virtual environments isolates project dependencies and prevents conflicts. They typically have their own
site-packagesdirectory.
Solutions
If Python can't find a module:
- Check Spelling: Ensure the module name is correctly spelled.
- Verify Location: Confirm that the module file exists in one of the directories on the search path.
- Add to
sys.path: If the module is in a non-standard location, usesys.path.append()to add it to the search path.
