Permanently add a directory to PYTHONPATH?

Ensuring Persistence Across Sessions

The additions to PYTHONPATH need to persist across multiple terminal sessions, for that, the export command needs to be placed in a startup file like ~/.bashrc (bash) or ~/.zshrc (Zsh). In a Unix-based system, you can opt to modify ~/.profile file or any other shell-specific startup scripts. On Windows, the setx command makes changes directly to the system's environmental variables, persisting these changes even after a reboot.

Making Use of .pth Files for an Organized Approach

Python provides a method to segregate your path additions using .pth files in the site-packages directory or user-site directories. You can find the path to user-site directory using:

python -m site --user-site


Inside a .pth file, add full path of directories (one per line) you want to include in PYTHONPATH. Compared to editing bash profiles, this method isolates Python-specific changes within the Python's own environment.

# so_many_paths.pth
/home/user/ProjectAlpha
/home/user/ProjectOmega


Procedural Precautions

While modifications to PYTHONPATH provide a way to make directories available across scripts, do avoid adding too randomly. Overloading the PYTHONPATH may lead to conflicts between module names, or unforeseen behavior in scripts. Always prefer utilizing virtual environments for project-specific dependencies.

Activating Changes Along the Way

Both editing the shell configuration files and .pth files require restart of your shell or system reboot for changes to take effect. Remember to either close and open your shell or reboot your system whenever you make changes to PYTHONPATH.

Temporary vs Permanent: Know the Difference

Using sys.path.append('/my/new/path') in your scripts only modifies the path for that Python session and is not a permanent solution. It's like a temporary pass into your module party, expires when the party's over.

import sys
sys.path.append('/my/terribly/temporary/path')
# Hey Python, here's a detour, but remember, it won't last!


Platform Specific Tips

For Windows users, the location of the site-packages directory may vary, always refer to the Python documentation of your installed version. Mac users, note that changes to ~/.bash_profile will be recognized only in new terminal sessions, not existing ones.

Up-to-Date Solutions

As Python evolves, there could be changes to how the environment variables are interpretation in newer version. Always check the Python documentation to ensure your export commands conform to the latest syntax.