Is it reliable and documented how PYTHONPATH populates the sys.path?

Question

On my machine, the values from PYTHONPATH appear to get inserted in sys.path:

• beginning at index 1
• order preserved
• de-duplicated

For example, with PYTHONPATH=/spam:/eggs:/spam and then checking in python -m site, I get a result like:

sys.path = [
    something,
    '/spam',
    '/eggs',
    more,
    stuff,
    after
]

It seems to be the same behaviour on Python 2 and Python 3. The question is, how much of this handling of PYTHONPATH is documented / reliable, and what if any might be different on other platforms? Is this baked into the interpreter, or is handled by site.py and/or in danger of being "tweaked" by sysadmins?

I can't see it explained in the documentation here, it just says sys.path is "augmented" (and, contrary to the documentation, non-existent directories do not appear to be silently ignored).

Answer 1

Let's go down the list.

---

• beginning at index 1

That's reliable. As stated in the PYTHONPATH docs,

The default search path is installation dependent, but generally begins with prefix/lib/pythonversion (see PYTHONHOME above). It is always appended to PYTHONPATH.

An additional directory will be inserted in the search path in front of PYTHONPATH as described above under Interface options. The search path can be manipulated from within a Python program as the variable sys.path.

One directory is inserted before PYTHONPATH, which may be the current directory, the script directory, or some other directory depending on how you ran Python. Other directories are appended. The site module will also add some modules to sys.path, but site appends too:

Importing this module will append site-specific paths to the module search path and add a few builtins...

---

• order preserved

I don't think this is explicitly documented anywhere, but search path order is important, and changing it is a backward compatibility break I don't think they would make lightly.

---

• de-duplicated

That's an undocumented effect of the site module. It won't happen if you run Python with the -S flag that disables site. You can see the code in site.removeduppaths