All 15 Modules & Packaging questions
More in Modules & Packaging
How does pyproject.toml serve as the modern standard for defining a Python package's build configuration and dependencies? What is __all__ and how does it control `from module import *` behavior? What is the purpose of a `requirements.txt` file, and how does it differ from dependency declarations in pyproject.toml? What does 'editable install' (pip install -e .) mean, and why is it useful during development? What is a namespace package, and how does it differ from a regular package? How does Python resolve circular imports, and what strategies avoid the resulting ImportError? How does importlib let you dynamically import a module by name at runtime? How do entry points in packaging metadata enable a package to register CLI commands or plugins? How does the module search and caching system handle submodule imports like `import package.subpackage.module`?
Advertisement
Back to results for “Debugging”
Python › Modules & Packaging

How does Python locate modules during import, and what is sys.path's role?

Advanced

Answer

When you import a module, Python searches directories listed in sys.path in order: the directory of the script being run (or '' for interactive/current directory), directories from the PYTHONPATH environment variable, and standard installation-dependent paths (including site-packages). The first matching module found wins, which is why sys.path order and accidental name shadowing (e.g., a local file named `json.py`) can cause confusing import bugs.
import sys
print(sys.path)  # list of directories searched, in order

sys.path.insert(0, '/custom/module/location')  # prioritize a custom path
import my_custom_module
Real-world example A developer's script mysteriously imports the wrong `requests` module because a local file named requests.py in the working directory shadows the installed package earlier in sys.path.

Common follow-ups: How do virtual environments modify sys.path?;What's the difference between sys.path and PYTHONPATH?

Virtual Environments & Dependency Management;Debugging & Profiling
All 15 Modules & Packaging questions