Как сделать EXE из Python-скрипта через PyInstaller: один файл и запуск без Python

Чтобы превратить Python-скрипт в EXE, собирайте его на Windows командой py -m PyInstaller --onefile app.py и забирайте готовый файл из папки dist. Начните с режима onedir, убедитесь, что программа запускается, и только потом переходите к одному файлу. PyInstaller кладёт внутрь интерпретатор и зависимости, поэтому на компьютере пользователя Python не нужен.

Обычно эта задача появляется после первого полезного скрипта: калькулятор работает из VS Code, но друг не хочет устанавливать Python и открывать терминал. EXE решает доставку, но не чинит ошибки программы. Если скрипт не запускается командой py app.py, сборка лишь упакует ту же проблему в более тяжёлый файл.

Что именно делает PyInstaller и где искать готовый файл

PyInstaller анализирует импорты, добавляет интерпретатор Python и нужные библиотеки, а затем создаёт автономный набор. Это упаковщик, а не компилятор исходника в машинный код. После команды рядом со скриптом появляются три объекта: служебная папка build, файл настроек .spec и результат в dist. Распространять нужно содержимое dist, а не случайный файл из build.

Исходник проходит анализ, а пользователю уходит только проверенный результат из dist.

Собираем первый EXE в отдельном окружении

Создайте папку проекта и файл hello.py. Виртуальное окружение отделит PyInstaller и библиотеки от других проектов. В PowerShell активируйте окружение, поставьте упаковщик через тот же интерпретатор и выполните сначала обычную сборку. Если команда py недоступна, используйте python в тех же строках.

# hello.py
name = input("Your name: ").strip() or "Developer"
print(f"Hello, {name}!")
input("Press Enter to close...")

# PowerShell в папке проекта
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install --upgrade pyinstaller
py -m PyInstaller hello.py

# После успешного теста
py -m PyInstaller --onefile --name HelloApp hello.py
.\dist\HelloApp.exe

Onedir проще чинить, onefile проще передавать. Начинать выгоднее с первого.

Когда выбирать onefile, onedir и windowed

Один EXE удобнее отправлять, но он распаковывает служебные файлы во временный каталог при каждом запуске. Режим onedir быстрее диагностировать: рядом видны библиотеки и ресурсы. Флаг --windowed подходит графическому приложению, но скрывает консоль вместе с сообщениями об ошибках. Не добавляйте его, пока сборка не стала стабильной.

Практика: собираем и проверяем HelloApp

Проверка должна повторять путь будущего пользователя. Не запускайте EXE только из терминала разработчика: там уже есть переменные окружения, библиотеки и привычная рабочая папка. Скопируйте результат в отдельный каталог и откройте двойным щелчком. Затем повторите запуск из PowerShell, чтобы увидеть код возврата и сообщения.

Симптом подсказывает уровень: код, импорт, ресурс или операционная система.

Почему EXE не запускается или теряет файлы

Если двойной щелчок ничего не показывает, откройте PowerShell, перейдите в dist и запустите EXE оттуда. Консоль сохранит traceback. Ошибки обычно относятся к одному из трёх уровней: исходный код, импорт библиотеки или путь к данным. Пересобирать десять раз одной командой бессмысленно, пока не определён уровень.