Concepts / Module Search Paths and sys.path

Module Search Paths and sys.path

A module does not need to be in one special universal location. It needs to be in the same directory as the importing program or in one of the directories listed in sys.path.

  • Programming
Interactive lab

Try it: What import Really Does

What happens on import: Python checks sys.modules, searches sys.path in order (first match wins), creates the module object, runs its top level once, then binds a name — the module, one function, or an alias — in the importing namespace; plus packages, __name__ == "__main__", ModuleNotFoundError and ImportError.

How it works

  1. If the name is already in sys.modules, reuse that module object: its code does not run again.
  2. Otherwise search each sys.path entry in order (the script's folder first); the first match wins, none raises ModuleNotFoundError.
  3. Create an empty module object, store it in sys.modules, then run the file's top level once (its __name__ is the module name, so a __main__ guard is skipped).
  4. import m binds m to the module; import m as x binds x; from m import f binds only f (ImportError if m has no f).
  5. A package runs its __init__.py first; submodules are found on the package's __path__ and become attributes of the package.

Default run (19 steps): $ python main.py — sys.path starts as [/project, /venv/site-packages, /usr/lib/python3.12]: the script's folder, then site-packages, then the standard library. Only our own modules are shown in sys.modules below. … Done. Printed: helpers loaded, __name__ = helpers | Hi Ann | Hi Ann.

Simplified: A fixed virtual project (main.py, helpers.py, pkg/, a site-packages folder and a one-file stand-in for the standard library). Built-in and frozen modules, .pyc caching, relative imports and namespace packages are not modelled; only our own modules are listed in sys.modules.

Educational simulation

Loading the simulation…

The Import Location Problem

When a program imports a module, the module must be located where Python can search for it. Python uses sys.path for this purpose. The entries in sys.path are directory names representing locations from which modules are imported.

Module requestrequested modulesys.path entry 1first locationsys.path entry 2next locationModule locationmodule can be importedinspectmodule is thereconsider another locationmodule is there
Which locations are considered when Python looks for an imported module?
Key point

A module does not need to be in one special universal location. It needs to be in the same directory as the importing program or in one of the directories listed in sys.path.

Reading sys.path

Definition

sys.path is the list of directory names where modules are imported from. Each entry identifies a location that can be used when Python searches for an importable module.

First entryempty stringCurrent directorypart of sys.pathLocal modulecan be importedindicatescontains
How does the empty first entry connect the search path with the current directory?

The first string in sys.path is empty. According to the source material, this empty string indicates that the current directory is also part of sys.path. Because of that entry, a module located in the current directory can be imported directly.

Tracing Module Locations

Worked example

A Module Beside the Importing Program

A program and a module are placed in the same directory. What does the module's location tell you about whether it can be imported?

  1. 1
    Locate the module

    The module is in the same directory as the program that imports it.

  2. 2
    Relate the location to sys.path

    The current directory is represented in sys.path by its empty first entry.

  3. 3
    Determine availability

    Because the current directory is part of sys.path, the module is in a directory from which Python can import modules.

Result

A module in the current directory can be imported directly.

sys.pathdirectory namesListed directoriespossible module locationsModuleslocated therelistscan contain
How do the directory names in sys.path connect to locations from which modules can be imported?

The important relationship is location-based: sys.path lists directory names, and modules placed in those directories are in locations from which Python can import them. If a module is not in the current directory, it must be placed in one of the other directories listed in sys.path.

Current directoryrepresented by empty entryModuledirectly importableAnother directorynot currentModulemust be listed in sys.pathcurrent directory is in sys.pathavailable when listed in sys.path
What changes when a module is in the current directory rather than in another directory?

Using PYTHONPATH

The source material connects the empty first sys.path entry and the current directory with the PYTHONPATH environment variable. The practical idea is to reason from the directories available through the module search path: a module can be imported when it is in the current directory or in a directory listed in sys.path.

PYTHONPATHenvironment settingsys.pathdirectory namesModule locationsdirectories available forimportassociated withidentifies
How does PYTHONPATH relate to the directories available for module searching?

Mistakes with Module Placement

  • Common mistake

    Assuming that a module can be imported from any directory.

    What it looks like

    A module is stored in a directory that is neither the current directory nor one of the directories listed in sys.path.

    Why it fails

    The source states that modules should be placed in the same directory as the importing program or in a directory listed in sys.path.

    Do this instead

    Place the module in the current directory or in one of the directories represented in sys.path.

  • Common mistake

    Treating the empty first sys.path entry as meaningless.

    What it looks like

    The first entry is empty, so it is ignored when deciding whether a local module is available.

    Why it fails

    The empty string indicates that the current directory is part of sys.path.

    Do this instead

    Interpret the empty first entry as the current directory.

  • Common mistake

    Confusing the module's name with its location.

    What it looks like

    A module has the expected name, but its directory is not represented in sys.path.

    Why it fails

    The search path is defined by directory names, and the module must be in an available directory.

    Do this instead

    Check the directory containing the module, not only the module's name.

Check Your Reasoning

EASY

A program imports a module. The module is not in the program's current directory. What must you check before deciding whether the module is available?

Hints
  • Think about the list of directory names used for module imports.
  • The module's directory must be represented in that list.

What do you think happens?

A module is placed in the current directory, and the first entry in sys.path is an empty string. Can the module be imported directly?

  • Yes

  • No

Reveal answer
Answer:

Yes

The empty first entry indicates that the current directory is part of sys.path. A module in the current directory is therefore in a location from which Python can import modules.

Key Takeaways

  1. 1
    sys.path is the list of directory names from which modules are imported.
  2. 2
    The empty first entry in sys.path indicates that the current directory is included.
  3. 3
    A module should be in the same directory as the importing program or in a directory listed in sys.path.
  4. 4
    The module's location matters because Python searches locations represented by the module search path.
  5. 5
    PYTHONPATH is associated in the source material with the directories available through the module search path.

At a glance

  • sys.path records directory names where modules are imported from.
  • Its empty first entry represents the current directory.
  • Modules outside the current directory must be placed in a directory listed in sys.path.
  • When an import is unavailable, inspect the module's directory and compare it with sys.path.

Related Topics

Related concepts

More concepts starting with M