Python Cookbook

Dynamically Changing the Python Search Path

Credit: Robin Parmar

Problem

Modules must be on the Python search path before they can be imported, but you don’t want a huge permanent path, because that slows things down—you want to change the path dynamically.

Solution

We just conditionally add a directory to Python’s sys.path, carefully checking to avoid duplication:

def AddSysPath(new_path):
    """ AddSysPath(new_path): adds a directory to Python's sys.path

    Does not add the directory if it does not exist or if it's already on
    sys.path. Returns 1 if OK, -1 if new_path does not exist, 0 if it was
    already on sys.path.
    """
    import sys, os

    # Avoid adding nonexistent paths
    if not os.path.exists(new_path): return -1

    # Standardize the path. Windows is case-insensitive, so lowercase
    # for definiteness.
    new_path = os.path.abspath(new_path)
    if sys.platform == 'win32':
        new_path = new_path.lower(  )

    # Check against all currently available paths
    for x in sys.path:
        x = os.path.abspath(x)
        if sys.platform == 'win32':
            x = x.lower(  )
        if new_path in (x, x + os.sep):
            return 0
    sys.path.append(new_path)
    return 1

if _ _name_ _ == '_ _main_ _':
    # Test and show usage
    import sys

    print 'Before:'
    for x in sys.path: print x

    if sys.platform == 'win32':
          print AddSysPath('c:\\Temp')
          print AddSysPath('c:\\temp')
    else:
          print AddSysPath('usr/lib/my_modules')

    print 'After:'
    for x in sys.path: print x

Discussion

Modules must be on the Python search path before they can be imported, but we don’t want to have a huge permanent path, because that would slow down every import performed by every Python script and application. This simple recipe dynamically adds a directory to the path, but only if that directory exists and was not already on sys.path.

sys.path is a list, so it’s easy to add directories to its end, using sys.path.append. Every import performed after such an append will automatically look in the newly added directory, if it cannot be satisfied from earlier ones.

It’s no big problem if sys.path ends up with some duplicates or if some nonexistent directory is accidentally appended to it; Python’s import statement is clever enough to shield itself against such issues. However, each time such a problem occurs at import time (from duplicate unsuccessful searches, errors from the operating system that need to be handled gracefully, etc.), there is a price to pay in terms of performance. To avoid the risk of these performance issues, this recipe does a conditional addition to sys.path, never appending any dictionary that doesn’t exist or is already in sys.path.

See Also

Documentation for the sys module in the Library Reference.