Превращаем Python-скрипт в исполняемый файл: полное руководство

Обновлено в 2026 году. Чтобы собрать exe из Python-скрипта, установите PyInstaller командой pip install -U pyinstaller и выполните pyinstaller --onefile script.py. Готовый исполняемый файл появится в папке dist рядом со скриптом. Запускается на компьютере без установленного Python. Ниже — все ключевые флаги, работа со .spec-файлом и разбор частых проблем: антивирус, размер, отсутствующие модули.

• Установка: pip install -U pyinstaller (нужен Python 3.8+).
• Одна команда: pyinstaller --onefile --noconsole script.py — один файл без чёрного окна консоли.
• Результат — в dist/; служебные файлы — в build/; настройки сборки — в .spec.
• Собрать под другую ОС нельзя: exe под Windows собирается только на Windows.
• Антивирус ругается на --onefile ложно — это известное поведение, лечится подписью и настройками.

Что делает PyInstaller и когда он нужен

PyInstaller упаковывает Python-скрипт вместе с интерпретатором и всеми зависимостями в один пакет, который запускается без установленного Python. Это снимает главную боль при раздаче программы: пользователю не нужно ставить Python, разбираться с версиями и pip. Он просто получает файл и кликает по нему.

Актуальная версия на момент обновления — PyInstaller 6.21.0. Инструмент поддерживает Python 3.8 и новее и официально тестируется на Windows, macOS и Linux (по данным официальной документации PyInstaller). Это не компилятор в машинный код и не обфускатор: питоновский байткод остаётся внутри, просто добавляется барьер для извлечения. Если цель — серьёзная защита исходников, PyInstaller её не решит, но для распространения обычного приложения его достаточно.

ОНЛАЙН-ПРАКТИКУМ

ЗАПУСК нейросети DEEPSEEK R1 ЛОКАЛЬНО НА СВОЕМ КОМПЬЮТЕРЕ

ЧТО БУДЕТ НА ОБУЧЕНИИ?

• ПОКАЖЕМ, КАК РАЗВЕРНУТЬ МОДЕЛЬ нейросети DEEPSEEK R1 ПРЯМО НА СВОЁМ КОМПЬЮТЕРЕ
• Где и как применять? Потестируем модель после установки на разных задачах
• Как дообучить модель под себя?

Участвовать бесплатно

Установка PyInstaller

Ставится как обычный пакет через pip:

pip install -U pyinstaller

Флаг -U обновляет до последней версии, если PyInstaller уже стоял. Проверить, что всё встало, можно так:

pyinstaller --version

Совет из практики: ставьте PyInstaller и все зависимости проекта в отдельное виртуальное окружение (python -m venv .venv). В глобальном Python обычно накоплены десятки лишних библиотек, и PyInstaller утянет их часть в сборку — итоговый файл разбухнет на пустом месте. Чистое окружение с ровно теми пакетами, что нужны скрипту, — самый простой способ держать размер под контролем.

Базовая сборка: одна команда

Самая короткая рабочая команда:

pyinstaller script.py

По умолчанию PyInstaller собирает приложение в режиме одной папки (--onedir, ключ -D): в dist/script/ лежит exe и рядом десятки файлов зависимостей. Такой вариант стартует быстрее и удобнее для отладки, но раздавать целую папку неудобно. Чаще нужен один файл:

pyinstaller --onefile script.py

После сборки в каталоге проекта появятся три сущности:

• dist/ — сюда падает готовый исполняемый файл. Именно эту папку (или один файл из неё) вы отдаёте пользователям.
• build/ — временные файлы, логи и промежуточные архивы. В раздачу не идёт, можно удалять.
• script.spec — текстовый файл с настройками сборки. О нём — отдельный раздел ниже.

Мини-вывод: для одного распространяемого файла — --onefile, для быстрого запуска и отладки — режим по умолчанию (папка).

Ключевые флаги PyInstaller

Всю сборку настраивают опции командной строки. Вот те, что закрывают 90% задач:

Флаги комбинируются. Типичная сборка GUI-программы с иконкой и именем:

pyinstaller --onefile --noconsole --name MyApp --icon app.ico script.py

Разделитель в —add-data: главная ловушка

Опция --add-data принимает пару «источник — папка назначения», но разделитель между ними зависит от ОС. На Windows это точка с запятой, на macOS и Linux — двоеточие. Один и тот же скрипт с копипастом команды с чужого сайта ломается именно здесь.

# Windows pyinstaller --onefile --add-data "assets;assets" script.py # macOS / Linux pyinstaller --onefile --add-data "assets:assets" script.py

Причина проста: на Windows двоеточие занято под букву диска (C:), поэтому в качестве разделителя выбрана точка с запятой. Забыли — и данные не попадут в сборку либо PyInstaller выдаст ошибку разбора аргумента.

Файл .spec: сборка без длинной команды

При первом запуске PyInstaller генерирует .spec — обычный Python-файл, куда записаны все параметры сборки. Дальше можно не набирать команду с десятком флагов, а собирать прямо из него:

pyinstaller script.spec

Внутри .spec — несколько объектов. Analysis собирает список скриптов, модулей и данных; PYZ — архив с байткодом; EXE строит исполняемый файл; COLLECT в режиме папки складывает итог (в режиме --onefile его нет). Чаще всего правят список данных внутри Analysis:

added_files = [ ('src/logo.png', '.'), ('config/*.json', 'config'), ] a = Analysis( ['script.py'], datas=added_files, hiddenimports=['pkg_resources.py2_warn'], ... )

Первая строка каждой пары — путь к файлу сейчас, вторая — папка внутри сборки, куда он попадёт во время работы программы. Держать сложную конфигурацию в .spec удобнее, чем в громоздкой команде: файл кладётся в репозиторий, и сборка воспроизводится одной строкой.

Кросс-платформенность: собрать под другую ОС нельзя

Частое заблуждение — что на Windows можно собрать exe для macOS или наоборот. Нельзя. PyInstaller не умеет кросс-компиляцию. По формулировке документации, если приложение нужно раздавать под несколько ОС, PyInstaller устанавливают на каждой платформе и собирают отдельно на каждой из них.

На практике это решают через виртуальные машины или CI: например, GitHub Actions с раннерами windows-latest, macos-latest и ubuntu-latest собирает три сборки за один прогон. Отдельный частный случай — Windows на macOS/Linux через Wine, но это хрупкий путь без гарантий, и держать его как основной способ не стоит.

Как уменьшить размер исполняемого файла

Файл на 30–80 МБ для маленького скрипта — норма для PyInstaller: внутри лежит весь интерпретатор Python. Сократить помогает несколько приёмов:

• Чистое виртуальное окружение. Собирайте из venv ровно с нужными пакетами — самый весомый эффект. PyInstaller упаковывает то, что видит установленным.
• Исключение модулей. Флаг --exclude-module выкидывает то, что скрипту не нужно, но затянулось по зависимостям (частый кандидат — tkinter в неграфических программах).
• UPX. PyInstaller умеет сжимать бинарники упаковщиком UPX — раздел «Using UPX» есть в документации. Осторожно: UPX-сжатие само по себе часто усиливает срабатывания антивирусов, так что это компромисс, а не бесплатное улучшение.
• Режим папки вместо onefile. --onedir не сжимает всё в один блок, стартует быстрее и реже ловит ложные детекты.

Частые проблемы и их решения

Антивирус помечает exe как вирус

Самая распространённая жалоба. Режим --onefile при запуске распаковывает содержимое во временную папку — ровно так же ведут себя многие упаковщики вредоносного ПО, поэтому эвристика антивируса срабатывает ложно. Что помогает: перейти на --onedir, не использовать UPX, подписать exe цифровой подписью (code signing), а также отправить файл в вендоры антивирусов как ложное срабатывание. Полностью проблема на стороне PyInstaller не решается — это плата за модель «интерпретатор в одном файле».

Программа падает: ModuleNotFoundError

PyInstaller ищет зависимости, анализируя import в коде. Но динамические импорты (через importlib, плагины, строковые имена модулей) он не видит. Такой модуль добавляют вручную:

pyinstaller --onefile --hidden-import missing_module script.py

Если библиотека тянет за собой целый набор скрытых импортов, обычно есть готовый hook или параметр --collect-all ИМЯ_ПАКЕТА, который забирает пакет целиком.

Не находятся картинки, шрифты, конфиги

Внешние файлы данных не попадают в сборку автоматически — их добавляют через --add-data (не забывая про разделитель ;/:). Внутри кода путь к таким файлам нужно строить относительно sys._MEIPASS — временной папки, куда PyInstaller распаковывает данные при запуске onefile-сборки.

Альтернативы PyInstaller

PyInstaller — не единственный вариант, и под конкретную боль иногда лучше подходит другой инструмент:

• auto-py-to-exe — графическая обёртка над самим PyInstaller. Удобно кликать флаги в окне вместо командной строки, но результат и все проблемы (включая ложные срабатывания антивируса) — те же, ведь под капотом тот же PyInstaller.
• Nuitka — компилирует Python в C и далее в настоящий бинарник. Из-за этого сборка выглядит для антивирусов как обычная программа и реже ловит ложные детекты; минус — дольше собирается и требовательнее к настройке.
• cx_Freeze — близок к режиму папки PyInstaller, без onefile-режима, а значит без распаковки, провоцирующей эвристику.
• Briefcase (проект BeeWare) — делает нативные установщики (MSI на Windows), к которым у антивирусов больше доверия.

Для типовой задачи «отдать программу человеку без Python» PyInstaller остаётся самым быстрым стартом. К Nuitka или Briefcase переходят, когда ложные детекты становятся системной проблемой.

Итоговый чек-лист сборки

• Создали venv, поставили только нужные пакеты и pip install -U pyinstaller.
• Собрали командой pyinstaller --onefile script.py (для GUI добавили --noconsole).
• Забрали результат из dist/, проверили запуск на чистой машине без Python.
• Данные (картинки, конфиги) добавили через --add-data с правильным разделителем.
• Скрытые модули дописали через --hidden-import, размер урезали через venv и --exclude-module.
• Помните: под каждую ОС собираем отдельно, на её же платформе.

Часто задаваемые вопросы

Как собрать exe одной командой?

Выполните pyinstaller --onefile script.py. Готовый файл появится в папке dist. Для приложения с интерфейсом добавьте --noconsole, чтобы убрать окно консоли.

Где лежит готовый exe после сборки?

В подпапке dist/ внутри каталога проекта. Папка build/ содержит только временные файлы и в раздачу не идёт.

Можно ли собрать exe для Windows на macOS или Linux?

Нет. PyInstaller не умеет кросс-компиляцию: сборку под каждую ОС делают на этой же ОС — через отдельную машину, виртуалку или CI вроде GitHub Actions.

Почему антивирус считает мой exe вирусом?

Это ложное срабатывание: режим --onefile распаковывает данные во временную папку так же, как это делают упаковщики вредоносного ПО. Помогает переход на --onedir, отказ от UPX и цифровая подпись файла.

Как уменьшить размер собранного файла?

Собирайте из чистого виртуального окружения, исключайте ненужные модули через --exclude-module и при необходимости включайте сжатие UPX. Основной вес — сам интерпретатор Python, полностью убрать его нельзя.

Что делать при ошибке ModuleNotFoundError в собранном файле?

Модуль импортируется динамически, и PyInstaller его не нашёл. Добавьте его явно: --hidden-import имя_модуля или заберите пакет целиком через --collect-all.

Чем auto-py-to-exe отличается от PyInstaller?

Это графическая надстройка над PyInstaller: те же возможности и те же проблемы, но флаги настраиваются в окне, а не в командной строке.