Local modules/packages

The first place python looks when you define an import is the "current" directory. The "current" directory depends on how you invoked your python application. If you invoke as a module, the "current" directory is your currentl location in the bash prompt (same as pwd). If you invoke as a script, the current directory is the folder that the file you invoked is located.

Example

Create a python file within a nested folder structure (and print the python path):

mkdir -p folder/subfolder/
echo 'import sys; print(sys.path)' > folder/subfolder/thing.py

Below are the two observed behaviours:

Running as a module:

$ python -m folder.subfolder.thing
>>> ['/Users/.../']

Running as a script:

$ python folder/subfolder/thing.py
>>> ['/Users/.../folder/subfolder']

This is particularly important when trying to use relative imports, especially ones that navigate parent directories (e.g. from ..something import something).

PYTHONPATH

The second place python looks when you define an import are the folders defined in the PYTHONPATH environment variable. This is a useful mechanism for including modules/packages located completely separately from your app on your machine.

If your app is a main.py file located in /Users/you/my-incredible-app/, but you have a super helpful python file located at /Users/Downloads/sweet_functions.py. You could set your environment variable with export PYTHONPATH='/Users/Downloads/' (or run your app with PYTHONPATH='/Users/Downloads/sweet_functions.py' python /Users/you/my-incredible-app/main.py) and your app's will be able to access functions using import sweet_functions.

It's common to set the PYTHONPATH to the root of your app to ensure packages/modules can be found. It's also common to "extend" the current PYTHONPATH rather than setting it explicitly: export PYTHONPATH=$PYTHONPATH:/Users/Downloads/.

The standard library

The third place Python looks for modules is the standard library. Python comes with several built-in modules (e.g. math, os, sys, json, typing, turtle, etc.). These modules are part of the Python standard library (and most are written in C for efficiency).

Third-party modules

The fourth place Python searches for modules is the site-packages directory. This is where third-party modules installed via tools like pip are stored. For example, if you have pip installed the "requests" library you can import it with import requests. You can use the site package to discover where site-packages is located:

$ python -c "import site; print(site.getsitepackages())"
>>> ['/Users/.../lib/python3.9/site-packages']

Summary

Python resolves imports in the order mentioned:

• Current Directory
• Python Path
• Standard Library
• Third-party modules

If a module can't be found in any of these locations, a ModuleNotFoundError is raised. Have fun!