Concepts / Module Search Paths and sys.path

Module Search Paths and sys.path

The sys.path contains the list of directory names where modules are imported from. Observe that the first string in sys.path is empty - this empty string indicates that the current directory is also part of the sys.path which is same as the PYTHONPATH environment variable. This means that you can directly import modules located in the current directory. Otherwise, you will have to place your module in one of the directories listed in sys.path .

  • Programming

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.

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

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

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.

indicatescontainsFirst entryempty stringCurrent directorypart of sys.pathLocal modulecan be imported
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

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?

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

Relate the location to sys.path: The current directory is represented in sys.path by its empty first entry.

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

A module in the current directory can be imported directly.

listscan containsys.pathdirectory namesListed directoriespossible module locationsModuleslocated there
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 directory is in sys.pathavailable when listed in sys.pathCurrent directoryrepresented by empty entryModuledirectly importableAnother directorynot currentModulemust be 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.

associated withidentifiesPYTHONPATHenvironment settingsys.pathdirectory namesModule locationsdirectories available forimport
How does PYTHONPATH relate to the directories available for module searching?

Mistakes with Module Placement

  • Assuming that a module can be imported from any directory.

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

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

  • Treating the empty first sys.path entry as meaningless.

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

    Fix: Interpret the empty first entry as the current directory.

  • Confusing the module's name with its location.

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

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

Key Takeaways

  • 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

  • Python Modules
  • Importing Modules
  • Environment Variables