Python shebang

A shebang is the first line of an executable script, beginning with #!. On POSIX systems, directly launching the script lets the operating system use that line to choose an interpreter. Running python3 script.py instead chooses the Python command explicitly; the shebang is then a Python comment.

This guide's executable checks ran on macOS with Python 3.12.14. POSIX shell commands are for macOS/Linux; Windows behavior is described separately and was not executed on a Windows host.

Create one script with an observable result

Save the following file as greet.py, using UTF-8 without a byte-order mark and LF line endings. The shebang must be the first bytes of the file.

#!/usr/bin/env python3
import sys
print("Hello from Python")
print(sys.version_info.major)

Expected output:

Hello from Python
3

For this ordinary script, /usr/bin/env finds python3 using the current PATH. It does not guarantee a particular minor version or virtual environment. PATH order is part of the execution contract; do not put untrusted directories first in privileged or automated jobs.

Run it explicitly, then run it as a program

python3 greet.py
chmod u+x greet.py
./greet.py

Both invocations print the two lines above. The first needs read permission on the script and an available interpreter. The second also needs executable permission, a valid interpreter line, and a filesystem that permits execution. The ./ explicitly selects the file in the current directory; most shells do not search the current directory by default.

Prove which Python was selected

import shutil
import sys
print(sys.executable != "")
print(shutil.which("python3") is not None)

Expected output:

True
True

For diagnosis, print the actual sys.executable path inside your script and compare it with command -v python3 in the shell. The values are machine-specific, so this guide does not invent a universal path. An activated virtual environment usually places its bin directory first on PATH. Without activation, run its interpreter explicitly, for example .venv/bin/python greet.py.

Choose between PATH lookup and an absolute interpreter

#!/usr/bin/env python3 is convenient when the caller should choose Python through PATH. A known absolute interpreter path is more explicit for a managed machine but may not exist elsewhere. Virtual-environment entry-point scripts normally reference their environment's interpreter; recreate the environment after moving the project instead of assuming those paths remain valid.

A shebang with multiple arguments is not uniformly portable. GNU env supports -S to split arguments, but support and operating-system parsing vary. For reproducible automation, supply interpreter options in the command or a reviewed launcher rather than assuming every machine parses a complex shebang identically.

Diagnose the failure before changing Python

Removing executable permission should make direct execution fail while explicit interpreter execution still works, provided the file remains readable. Error wording differs by operating system and shell. Do not “fix” a missing package by installing it into an unrelated global interpreter.

Windows is a separate launching mechanism

Windows does not use the POSIX kernel shebang mechanism. Python's Windows launcher/install-manager tooling can recognize supported shebang forms, but file associations and launcher configuration affect direct opening. Use an explicit environment interpreter, such as .venv\Scripts\python.exe greet.py, when the selected environment matters. A shebang is neither a package installer nor an environment lock file.

References: executable Python scripts, virtual environment mechanics, env invocation, and Python on Windows.