Introduction

PYTHONPATH is usually not the answer when you want to run a script from any directory. PYTHONPATH helps Python find modules for import, but your shell uses PATH to find executable commands. If the goal is "type one command anywhere and run my script," you normally solve that with PATH, a shebang, or packaging the script as a console entry point.

Understand PATH Versus PYTHONPATH

These two variables do different jobs:

• 'PATH: searched by the shell to find commands to execute'
• 'PYTHONPATH: searched by the Python interpreter to find modules to import'

If you type myscript in a terminal, your shell checks PATH. It does not check PYTHONPATH to decide where the command lives.

That is why adding your script directory to PYTHONPATH will not usually let you execute the script by name.

Option 1: Put the Script Directory on PATH

If you want a direct command, the simplest approach is to put the directory that contains the script on your system PATH.

On macOS or Linux, you might add this to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/bin:$PATH"

Then place your script in $HOME/bin and make it executable.

#!/usr/bin/env python3
print("hello from my script")

chmod +x ~/bin/myscript
myscript

Now the shell can find myscript from any directory.

Option 2: Run It Explicitly With Python and an Absolute Path

If you do not want to modify PATH, you can still run the script from anywhere by calling Python with the full path.

python3 /Users/markqian/tools/myscript.py

This is simple and reliable, but it is not as convenient as a named command.

Option 3: Package It as a Console Script

For reusable developer tools, the best long-term solution is often to package the script and expose a console entry point. That way installation creates a command automatically in the environment's script directory.

1[project]
2name = "mytool"
3version = "0.1.0"
4
5[project.scripts]
6mytool = "mytool.cli:main"

# mytool/cli.py
def main():
    print("running mytool")

After installing the package, you can run:

mytool

This is cleaner than scattering ad hoc scripts across manually managed directories.

When PYTHONPATH Actually Matters

PYTHONPATH is useful when your script imports modules from custom directories that are not installed as packages.

export PYTHONPATH="/Users/markqian/dev/shared_libs:$PYTHONPATH"
python3 /Users/markqian/tools/myscript.py

That helps the script's imports resolve, but it still does not make myscript.py itself discoverable as a shell command.

For application code, packaging the shared module properly is usually better than leaning on PYTHONPATH everywhere.

Use Aliases Sparingly

Another possible shortcut is a shell alias.

alias myscript='python3 /Users/markqian/tools/myscript.py'

This works for personal workflows, but it is shell-specific and less portable than a real executable or packaged command.

It is fine for a quick local convenience, but not ideal as the long-term distribution story for a team tool.

Common Pitfalls

The most common mistake is using PYTHONPATH when the real problem is command discovery. The shell uses PATH, not PYTHONPATH, to find executables.

Another issue is putting a script on PATH without making it executable or without adding a shebang line. On Unix-like systems, both details matter.

Developers also often rely on aliases and then forget those aliases do not exist on other machines, in CI, or in a fresh shell.

Finally, if the script has complex imports, do not solve every import error with more PYTHONPATH. Packaging the code properly is usually the cleaner answer.

Summary

• 'PYTHONPATH is for imports, not for locating commands in the shell.'
• Use PATH plus a shebang and executable permissions when you want to run a script by name.
• Use an absolute path if you only need a simple manual command.
• Package the script with a console entry point for the cleanest reusable solution.
• Reserve PYTHONPATH for import resolution, not command discovery.