PYTHONPATH is an environment variable in Python that tells the interpreter where to look for modules and packages when importing them.

It essentially extends Python’s default search path (sys.path) so that you can import your own custom modules from non-standard directories.

🔹 In Simple Terms

When you use:

import mymodule

import mymodule

Python searches for mymodule in these locations (in order):

1. The current working directory
2. The directories listed in the PYTHONPATH environment variable
3. The default installation directories (like /usr/lib/pythonX.Y/ or the site-packages folder)

If the module isn’t found in any of these, you’ll get:

ModuleNotFoundError: No module named 'mymodule'

ModuleNotFoundError: No module named 'mymodule'

🔹 Example: Viewing the Current Python Search Path

You can check where Python looks for modules using:

import sys
print(sys.path)

import sys
print(sys.path)

Output (example):

['', '/usr/lib/python311.zip', '/usr/lib/python3.11', '/usr/lib/python3.11/lib-dynload', '/usr/local/lib/python3.11/dist-packages']

['', '/usr/lib/python311.zip', '/usr/lib/python3.11', '/usr/lib/python3.11/lib-dynload', '/usr/local/lib/python3.11/dist-packages']

If you add a custom directory to PYTHONPATH, it will also appear in this list.

🔹 Setting PYTHONPATH Temporarily

You can temporarily set PYTHONPATH in your terminal before running Python.

✅ On Windows (Command Prompt):

set PYTHONPATH=C:\Users\Dheeraj\my_modules
python myscript.py

set PYTHONPATH=C:\Users\Dheeraj\my_modules
python myscript.py

✅ On Linux / macOS (Bash or Zsh):

export PYTHONPATH=/home/dheeraj/my_modules
python3 myscript.py

export PYTHONPATH=/home/dheeraj/my_modules
python3 myscript.py

Now, Python will also search for modules inside /home/dheeraj/my_modules.

🔹 Setting PYTHONPATH Permanently

To make it permanent:

🪟 Windows

• Open Environment Variables (System Properties → Advanced → Environment Variables)
• Add a new variable:
  • Name: PYTHONPATH
  • Value: Path to your modules (e.g., C:\Users\Dheeraj\my_modules)

🐧 Linux/macOS

• Add this line to your .bashrc or .zshrc: export PYTHONPATH="/home/dheeraj/my_modules:$PYTHONPATH"
• Then reload: source ~/.bashrc

🔹 Example: Using PYTHONPATH

Suppose you have this structure:

project/
│
├── main.py
└── my_lib/
    └── helper.py

project/
│
├── main.py
└── my_lib/
    └── helper.py

Normally, to import helper inside main.py, both files should be in the same folder.
But if they’re not, you can set PYTHONPATH to include my_lib.

export PYTHONPATH=/path/to/my_lib
python main.py

export PYTHONPATH=/path/to/my_lib
python main.py

Now in main.py, you can write:

import helper
helper.some_function()

import helper
helper.some_function()

🔹 Adding Path Dynamically in Code

You can also modify the path inside a Python script itself:

import sys
sys.path.append("/home/dheeraj/my_modules")

import mymodule  # Now works

import sys
sys.path.append("/home/dheeraj/my_modules")

import mymodule  # Now works

🔹 Why PYTHONPATH is Important

🔹 In Summary

✅ In short:

PYTHONPATH is an environment variable that extends Python’s module search path, allowing you to import your own modules from custom directories outside the default library locations.