Basics

What is a shebang — and why a script from Windows fails with python3\r

Illustration: a scroll with a tag at the top; a string runs from the tag to one of the machines, and only that one is switched on

Here's a weird one. You download a script, run ./deploy.py — and get:

/usr/bin/env: ‘python3\r’: No such file or directory

Python is installed. The file is right there. Yet the system is hunting for a program with a strange \r on the end. The culprit is the file's first line — the one with a hash and an exclamation mark. It's called a shebang, and it has a couple of non-obvious rules.

What a shebang is, in plain words

A shebang is the first line of a script that starts with #! and tells the system which program should run the file.

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

The name glues two bits of jargon together: # is often called sharp or hash, and ! is bang. Put them together and you get shebang.

Think of a label on a parcel: "open only in the Python department". What's inside is just text. The label decides who gets it.

How it works

When you type ./deploy.py, the Linux or macOS kernel opens the file and looks at the first two bytes. If they're #!, the kernel reads the rest of the line as the path to a program. Then it runs that program and hands your file to it as an argument.

So ./deploy.py actually becomes:

/usr/bin/env python3 ./deploy.py

Then env looks up python3 in your PATH and passes it the file. For Python, the #!... line is just a comment, so it skips it.

That gives you the first surprising rule: only the kernel reads the shebang, and only when you run the file by its path. If you type bash deploy.sh or python3 deploy.py, you picked the program yourself. The first line then changes nothing at all.

Why /usr/bin/env instead of the Python path

You could write it directly: #!/usr/bin/python3. That works — as long as Python lives exactly there.

Often it doesn't. On a Mac with Homebrew it's in /opt/homebrew/bin. In a virtual environment it's inside the project folder. Some people use pyenv.

env solves this in one move: it finds the program via PATH, as if you'd typed its name in the terminal. That's why nearly every modern script starts with #!/usr/bin/env python3 or #!/usr/bin/env node. And env itself sits in /usr/bin almost everywhere.

There's a flip side. Activate the wrong environment and the script runs with the wrong Python. For system scripts that's sometimes worse than a hard-coded path.

Three traps everyone trips on

1. A file from Windows. Windows ends lines with two characters: \r\n. Linux expects just \n. The kernel honestly reads the line up to \n — and the \r sticks to the program name. Hence python3\r, which doesn't exist. Fix it by converting the line endings: sed -i 's/\r$//' deploy.py, or set your editor to LF.

2. Options in the shebang. Want to give Node more memory, so you write #!/usr/bin/env node --max-old-space-size=4096? On Linux the kernel passes everything after the path as one chunk. So env looks for a program literally named node --max-old-space-size=4096. We tested it: GNU env immediately hints use -[v]S to pass options in shebang lines. The working version:

#!/usr/bin/env -S node --max-old-space-size=4096

3. sh is not bash. The script starts with #!/bin/sh, and inside there's [[ ... ]]. Via bash script.sh everything works. Via ./script.sh it dies with [[: not found. Why: on Ubuntu /bin/sh is dash, a stripped-down shell that doesn't know bash syntax. Writing bash things? Use #!/usr/bin/env bash.

Where you'll meet a shebang

  • Scripts in npm packages' bin. When you install a CLI via npm, its JS file starts with #!/usr/bin/env node. Without that line the command wouldn't run.
  • Scripts written by AI. Claude or Codex almost always add a shebang themselves. Worth a glance: is it sh or bash, and does the Python version match?
  • Git hooks. Files in .git/hooks are scripts with a shebang too. By the way, a hook can even be written in Python.

A shebang needs one more thing: execute permission. Without chmod +x the kernel won't even get to the first line. And if the script breaks in the middle rather than at the start, check how it handles spaces in file names.

What happens if there's no shebang?

Bash and zsh will run the file with themselves. We checked: a script with no first line ran in bash. But that's the shell's behavior, not the kernel's — launched from another program, the same file may fail to start.

Does a shebang work on Windows?

Windows itself doesn't understand it. But Git Bash and WSL do, and the py launcher for Python reads the shebang to pick a version.

Does the shebang have to be the very first line?

Yes. Even an empty line or an invisible BOM before #! — and the kernel won't see it. So save scripts as UTF-8 without a BOM.

Want to get this stuff without cramming? In KODiQ it's short five-minute lessons — the terminal, scripts and AI agents in plain words.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →