Что такое…

Что такое шебанг — и почему скрипт с Windows падает с ошибкой python3\r

Иллюстрация: свиток с биркой наверху, от бирки тянется нитка к одной из машин — включена только она

Смотри, какая штука. Ты скачал скрипт, запускаешь ./deploy.py — и получаешь:

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

Python установлен. Файл на месте. А система ищет программу с каким-то \r на конце. Виновата первая строчка файла — та самая, с решёткой и восклицательным знаком. Она называется шебанг, и у неё есть пара неочевидных правил.

Что такое шебанг простыми словами

Шебанг — это первая строка скрипта, которая начинается с #! и говорит системе, какой программой этот файл исполнять.

#!/usr/bin/env python3
print("привет")

Название — склейка двух жаргонных слов: # по-английски часто зовут sharp или hash, а ! — bang. Вместе вышло shebang.

Представь бирку на посылке «вскрывать только в отделе Python». Сам текст внутри — просто текст. Бирка решает, кому его отдать.

Как это работает

Когда ты пишешь ./deploy.py, ядро Linux или macOS открывает файл и смотрит на первые два байта. Если там #!, ядро читает остаток строки как путь к программе. И запускает уже её, подсовывая твой файл как аргумент.

То есть ./deploy.py на самом деле превращается в:

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

А дальше env ищет python3 в твоём PATH и передаёт ему файл. Сама строка #!... для Python — обычный комментарий, он её пропускает.

Отсюда первое неожиданное правило: шебанг читает только ядро и только при запуске через путь. Если ты пишешь bash deploy.sh или python3 deploy.py, ты сам выбрал программу. Первая строка тогда вообще ни на что не влияет.

Почему /usr/bin/env, а не путь к Python

Можно написать прямо: #!/usr/bin/python3. Работает — пока Python лежит именно там.

А он часто лежит не там. На Маке с Homebrew — в /opt/homebrew/bin. В виртуальном окружении — внутри папки проекта. У кого-то стоит pyenv.

env решает это одним ходом: он ищет программу по PATH, как будто ты набрал её имя в терминале. Поэтому почти все современные скрипты начинаются с #!/usr/bin/env python3 или #!/usr/bin/env node. Сам env при этом лежит в /usr/bin практически везде.

Есть и обратная сторона. Активировал не то окружение — и скрипт запустится не тем Python. Для системных скриптов это иногда хуже, чем жёсткий путь.

Три ловушки, на которых спотыкаются все

1. Файл с Windows. Windows заканчивает строки двумя символами: \r\n. Linux ждёт только \n. Ядро честно читает строку до \n — и \r прилипает к имени программы. Отсюда python3\r, которого нет. Лечится переводом концов строк: sed -i 's/\r$//' deploy.py или настройкой редактора на LF.

2. Опции в шебанге. Хочешь дать Node больше памяти и пишешь #!/usr/bin/env node --max-old-space-size=4096? На Linux ядро передаёт всё после пути одним куском. И env ищет программу с именем node --max-old-space-size=4096 целиком. Мы проверили: GNU env тут же подсказывает use -[v]S to pass options in shebang lines. Рабочий вариант:

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

3. sh — это не bash. Скрипт начинается с #!/bin/sh, а внутри — [[ ... ]]. Через bash script.sh всё работает. Через ./script.sh падает с [[: not found. Почему: на Ubuntu /bin/sh — это урезанная оболочка dash, она не знает bash-синтаксиса. Пишешь bash-штуки — ставь #!/usr/bin/env bash.

Где ты встретишь шебанг

  • Скрипты в bin npm-пакетов. Когда ставишь CLI через npm, в начале его JS-файла стоит #!/usr/bin/env node. Без этой строки команда бы не запустилась.
  • Скрипты от ИИ. Claude или Codex почти всегда ставят шебанг сами. Полезно глянуть, какой: sh или bash, и совпадает ли версия Python.
  • Хуки Git. Файлы в .git/hooks — тоже скрипты с шебангом. Кстати, хук может быть хоть на Python.

Шебангу нужно ещё одно условие: право на исполнение. Без chmod +x ядро до первой строки даже не дойдёт. А если скрипт ломается в середине, а не на старте — глянь, как он обращается с пробелами в именах.

Что будет, если шебанга нет?

Bash и zsh запустят файл сами собой. Мы проверили: скрипт без первой строки выполнился в bash. Но это поведение оболочки, а не ядра — из другой программы такой файл может не запуститься.

Работает ли шебанг на Windows?

Сама Windows его не понимает. Но Git Bash и WSL понимают, а лаунчер py для Python читает шебанг и выбирает версию.

Шебанг должен быть строго первой строкой?

Да. Даже пустая строка или невидимый BOM перед #! — и ядро его не увидит. Поэтому сохраняй скрипты в UTF-8 без BOM.

Хочешь разбираться в таких штуках без зубрёжки? В KODiQ это короткие уроки по пять минут — терминал, скрипты и ИИ-агенты простыми словами.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →