What is PYTHONPATH environment variable in Python?

In Python, PYTHONPATH is an environment variable that specifies additional directories where Python searches for modules during imports. When you import a module, Python searches through directories listed in sys.path, which includes the current working directory, standard library paths, and any directories specified in PYTHONPATH.

PYTHONPATH allows you to add custom directories containing your Python modules without installing them in the global site-packages directory. This is particularly useful for maintaining project-specific libraries or when you don't have permissions to install packages globally.

What is PYTHONPATH?

PYTHONPATH is an environment variable that extends Python's module search path. When Python imports a module, it searches directories in this order:

• Current working directory
• Standard library directories
• Directories in PYTHONPATH
• Site-packages directory

Let's see how Python's module search path works ?

import sys
print("Python module search paths:")
for path in sys.path:
    print(f"  {path}")

Python module search paths:
  /current/working/directory
  /usr/lib/python39.zip
  /usr/lib/python3.9
  /usr/lib/python3.9/lib-dynload
  /home/user/.local/lib/python3.9/site-packages
  /usr/local/lib/python3.9/dist-packages

Setting PYTHONPATH in Terminal

You can set PYTHONPATH before running Python scripts. This method is temporary and only affects the current session ?

# Linux/macOS
export PYTHONPATH="/path/to/my/modules:$PYTHONPATH"
python my_script.py

# Windows
set PYTHONPATH=C:\path\to\my\modules;%PYTHONPATH%
python my_script.py

Modifying sys.path in Python

You can programmatically modify the module search path within your Python script ?

import sys
import os

# Add directory to the beginning of search path
sys.path.insert(0, '/path/to/my/modules')

# Add directory to the end of search path  
sys.path.append('/path/to/another/modules')

# Verify the changes
print("Updated sys.path:")
for i, path in enumerate(sys.path[:3]):
    print(f"  {i}: {path}")

Updated sys.path:
  0: /path/to/my/modules
  1: /current/working/directory
  2: /path/to/another/modules

Using .pth Files

Path configuration files (.pth) provide a permanent way to extend the module search path. Create a .pth file in the site-packages directory ?

# Create mymodules.pth in site-packages directory
# Content of the file:
/path/to/my/modules
/path/to/another/modules

Using Virtual Environments

Virtual environments automatically manage PYTHONPATH for project isolation ?

# Create virtual environment
python -m venv myproject_env

# Activate virtual environment
# Linux/macOS:
source myproject_env/bin/activate
# Windows:
myproject_env\Scripts\activate

# Install packages (goes to virtual env, not global)
pip install requests

Comparison of Methods

Best Practices

When working with PYTHONPATH, follow these recommendations:

• Use virtual environments for project isolation
• Avoid setting global PYTHONPATH permanently
• Use relative imports within packages when possible
• Document any PYTHONPATH requirements for your project

Conclusion

PYTHONPATH is a powerful tool for customizing Python's module search behavior. Use virtual environments for project isolation and sys.path modification for dynamic runtime changes. Choose the method that best fits your development workflow and project requirements.