Как сделать исполняемый файл из скрипта Python

Вы завидуете разработчикам Go, которые создают исполняемый файл и легко доставляют его пользователям? Разве не было бы замечательно, если бы ваши пользователи могли запускать ваше приложение, ничего не устанавливая? Это мечта и PyInstaller — один из способов добиться этого в экосистеме Python.

Существует бесчисленное множество руководств по настройке виртуальных сред, управления зависимостями и опубликованием в PyPI, что полезно при создании библиотек Python. Для разработчиков, создающих приложения Python, информации гораздо меньше. Этот урок для те, кто хочет распространять приложения среди пользователей, которые могут быть не только разработчиками Python.

В этом уроке вы узнаете:

• Как PyInstaller может упростить распространение приложений
• Как использовать PyInstaller в ваших собственных проектах
• Как отлаживать ошибки PyInstaller
• Что PyInstaller не может

PyInstaller дает вам возможность создать папку или исполняемый файл, который пользователи могут сразу запустить без дополнительной установки. Чтобы полностью оценить возможности PyInstaller, полезно еще раз вернуться к некоторым проблемам распространения, которых помогает избежать PyInstaller.

Содержание

Проблемы распространения ↑

Настройка проекта Python может быть неприятной, особенно для не разработчиков. Часто установка начинается с открытия Терминала, который не запускается для огромной группы потенциальных пользователей. Это препятствие останавливает пользователей еще до того, как руководство по установке углубится в сложные детали виртуальных сред, версий Python и т.д. и множество потенциальных зависимостей.

Вспомните, через что вы обычно проходите, настраивая новую машину для разработки Python. Вероятно, это выглядит примерно так:

• Загрузите и установите нужную версию Python;
• Настроить менеджер зависимостей;
• Настроить виртуальную среду;
• Получить копию своего кода;
• Установить зависимости.

Остановитесь на мгновение и подумайте, есть ли смысл в любом из вышеперечисленных шагов, если вы не разработчик, не говоря уже о разработчике Python. Возможно нет.

Эти проблемы взорвутся, если вашему пользователю посчастливится добраться до части установки, связанной с зависимостями. Это стало намного лучше за последние несколько лет с преобладанием колес, но для некоторых зависимостей по-прежнему требуются компиляторы C/C++ или даже FORTRAN!

Этот барьер для входа слишком высок, если ваша цель — сделать приложение доступным как можно большему количеству пользователей. Как часто говорит Раймонд Хеттингер в своих замечательных выступлениях:

PyInstaller ↑

PyInstaller скрывает эти детали от пользователя, находя все ваши зависимости и объединяя их вместе. Ваши пользователи даже не узнают, что они запускают проект Python, потому что интерпретатор Python встроен в ваше приложение. Прощай, сложная инструкция по установке!

PyInstaller выполняет этот удивительный подвиг, анализируя ваш код Python, обнаруживая ваши зависимости, а затем упаковывая их в подходящий формат в зависимости от вашей операционной системы.

В PyInstaller есть много интересных тонкостей, но здесь пока вы узнаете только основы того, как он работает и как его использовать. Вы всегда можете обратиться к отличной документации PyInstaller, если хотите получить более подробную информацию.

Кроме того, PyInstaller может создавать исполняемые файлы для Windows, Linux или macOS. Это означает, что пользователи Windows получат .exe, пользователи Linux получат обычный исполняемый файл, а пользователи macOS получат пакет .app. На этот счет есть некоторые предостережения. См. Раздел ограничений для получения дополнительной информации.

Подготовка проекта ↑

PyInstaller требует, чтобы ваше приложение соответствовало некоторой минимальной структуре, а именно, чтобы у вас был сценарий CLI для запуска вашего приложения. Часто это означает создание небольшого скрипта вне вашего пакета Python, который просто импортирует ваш пакет и запускает main().

Скрипт точки входа — это скрипт Python. Технически вы можете делать в сценарии точки входа все, что захотите, но вам следует избегать использования явного относительного импорта. Вы по-прежнему можете использовать относительный импорт во всем остальном приложении, если это ваш стиль.

Примечание. Точка входа — это код, с которого запускается ваш проект или приложение.

Вы можете попробовать это в своем собственном проекте или попробовать на проекте чтения каналов Real Python. Для получения более подробной информации о проекте для чтения ознакомьтесь с руководством по публикации пакета на PyPI.

Первым шагом к созданию исполняемой версии такого проекта является добавление сценария точки входа. К счастью,проект программы чтения каналов хорошо структурирован, поэтому все, что вам нужно, это небольшой сценарий вне пакета для его запуска. Например, вы можете создать файл с именем cli.py вместе с пакетом для чтения со следующим кодом:

Этот скрипт cli.py вызывает main() для запуска программы чтения каналов.

Создать этот сценарий точки входа несложно, когда вы работаете над собственным проектом, потому что вы знакомы с кодом. Однако найти точку входа в чужой код не так просто. В этом случае вы можете начать с просмотра файла setup.py в третьем -партийный проект.

Найдите ссылку на аргумент entry_points в файле setup.py проекта. Например, вот проект для чтения setup.py:

Как видите, сценарий cli.py точки входа вызывает ту же функцию, что и аргумент entry_points.

После этого изменения каталог проекта ридера должен выглядеть так, если вы извлекли его из папки с именем reader:

Обратите внимание, что сам код считывателя не изменился, только новый файл с именем cli.py. Этот сценарий точки входа обычно является всем, что необходимо для использования вашего проекта с PyInstaller.

Однако вам также стоит обратить внимание на использование __import__() или импорта внутри функций. В терминологии PyInstaller они называются скрытым импортом. Вы можете вручную указать скрытый импорт, чтобы PyInstaller включил эти зависимости, если изменение импорта в вашем приложении слишком сложно. Вы увидите, как это сделать позже в этом руководстве.

Как только вы сможете запустить свое приложение с помощью скрипта Python вне вашего пакета, вы готовы попробовать PyInstaller при создании исполняемого файла.

Использование PyInstaller ↑

Первый шаг — установить PyInstaller из PyPI. Это можно сделать, используя pip, как и для других пакетов Python:

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

Вы будете использовать интерфейс библиотеки, если будете создавать свои собственные файлы ловушек.

Вы увеличите вероятность того, что по умолчанию PyInstaller создаст исполняемый файл, если у вас есть только чистые зависимости Python. Однако не стоит особо беспокоиться, если у вас более сложные зависимости от расширений C/C++.

PyInstaller поддерживает множество популярных пакетов, таких как NumPy, PyQt и Matplotlib, без каких-либо дополнительных действий с вашей стороны. Вы можете узнать больше о списке пакетов, которые PyInstaller официально поддерживает, обратившись к документации PyInstaller.

Не беспокойтесь, если некоторые из ваших зависимостей не указаны в официальной документации. Многие пакеты Python работают нормально. Фактически, PyInstaller достаточно популярен, поэтому во многих проектах есть объяснения, как заставить вещи работать с PyInstaller.

Одним словом, шансы на то, что ваш проект сработает «из коробки», высоки.

Чтобы попробовать создать исполняемый файл со всеми значениями по умолчанию, просто дайте PyInstaller имя вашего основного сценария точки входа.

Сначала cd в папку с вашей записью — укажите и передайте его в качестве аргумента команде pyinstaller, которая была добавлена ​​в ваш PATH при установке PyInstaller.

Например, введите следующее после того, как вы cd в каталог программы чтения верхнего уровня, если вы подписаны на проект вместе с проектом чтения каналов:

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

Копаемся в артефактах PyInstaller ↑

PyInstaller сложен внутри и при работе создаёт массу информации. Итак, важно знать, на чем сосредоточиться в первую очередь. А именно исполняемый файл, который вы можете распространять среди пользователей, и потенциальную отладочную информацию. По умолчанию команда pyinstaller создает несколько интересных моментов:

• Файл спецификации *.spec
• Папка сборки Build
• Папка дистрибутива Dist

Файл спецификаций ↑

По умолчанию файл спецификации будет назван в честь вашего сценария командной строки. Продолжая наш предыдущий пример, вы увидите файл с именем cli.spec. Вот как выглядит файл спецификации по умолчанию после запуска PyInstaller в файле cli.py:

Этот файл будет автоматически создан командой pyinstaller. У вашей версии будут разные пути, но большинство должно быть одинаковым.

Не волнуйтесь, вам не нужно понимать приведенный выше код, чтобы эффективно использовать PyInstaller!

Этот файл можно изменить и повторно использовать для создания исполняемых файлов позже. Вы можете сделать будущие сборки немного быстрее, предоставив этот файл спецификации вместо сценария точки входа для команды pyinstaller.

Есть несколько конкретных вариантов использования файлов спецификации PyInstaller. Однако для простых проектов вам не нужно беспокоиться об этих деталях, если вы не хотите сильно настраивать способ сборки вашего проекта.

Папка сборки Build ↑

Папка build — это то место, куда PyInstaller помещает большую часть метаданных и внутренней бухгалтерии для создания вашего исполняемого файла. Содержимое по умолчанию будет выглядеть примерно так:

Папка сборки может быть полезна для отладки, но, если у вас нет проблем, эту папку можно в значительной степени игнорировать. Вы узнаете больше об отладке позже в этом уроке.

Папка Dist ↑

После сборки вы получите папку dist, подобную следующей:

Папка dist содержит последний вариант приложения, который вы хотите отправить своим пользователям. Внутри папки dist есть папка, названная в честь вашей точки входа. Итак, в этом примере у вас будет папка dist/cli, содержащая все зависимости и исполняемый файл для нашего приложения. Исполняемый файл для запуска — dist/cli/cli или dist/cli/cli.exe, если вы работаете в Windows.

Вы также найдете множество файлов с расширениями .so, .pyd и .dll в зависимости от вашей операционной системы. Это общие библиотеки, которые представляют зависимости вашего проекта, которые PyInstaller создал и собрал.

Примечание. Вы можете добавить *.spec, build и dist в свой файл .gitignore, чтобы сохранить статус git в чистоте, если вы используете git для контроля версий. Файл gitignore GitHub по умолчанию для проектов Python уже делает это за вас.

Вы захотите распространить всю папку dist/cli, но вы можете переименовать cli во все, что вам подходит.

На этом этапе вы можете попробовать запустить исполняемый файл dist/cli/cli.exe, если вы следуете примеру программы чтения каналов.

Вы заметите, что запуск исполняемого файла приводит к ошибкам, в которых упоминается файл version.txt. Это связано с тем, что программе чтения каналов и ее зависимостям требуются некоторые дополнительные файлы данных, о которых PyInstaller не знает. Чтобы исправить это, вам нужно сообщить PyInstaller, что требуется version.txt, о чем вы узнаете при тестировании нового исполняемого файла.

Настройка ваших сборок ↑

У PyInstaller есть множество параметров, которые могут быть предоставлены в виде файлов спецификаций или обычных параметров интерфейса командной строки (CLI). Ниже вы найдете некоторые из наиболее распространенных и полезных настроек.

—name — изменить имя исполняемого файла

Это способ избежать того, чтобы ваши исполняемый файл, файл спецификации и папки артефактов сборки были названы в честь вашего сценария точки входа. —name полезно, если у вас есть привычка называть сценарий точки входа чем-то вроде cli.py, как это делаю я.

Вы можете создать исполняемый файл под названием realpython из cli.py скрипт с такой командой:

—onefile — упакуйте все приложение в один исполняемый файл

Параметры по умолчанию создают папку зависимостей и исполняемого файла, тогда как —onefile упрощает распространение, создавая только исполняемый файл.

Эта опция не требует аргументов. Чтобы объединить свой проект в один файл, вы можете выполнить сборку с помощью такой команды:

С помощью приведенной выше команды ваша папка dist/ будет содержать только один исполняемый файл вместо папки со всеми зависимостями в отдельных файлах.

—hidden-import — перечислите несколько операций импорта верхнего уровня, которые PyInstaller не смог обнаружить автоматически.

Это один из способов обойти ваш код, используя импорт внутри функций и __import __() . Вы также можете использовать —hidden-import несколько раз в одной команде.

Эта опция требует имени пакета, который вы хотите включить в свой исполняемый файл.. Например, если ваш проект импортировал библиотеку запросов внутри функции, PyInstaller не будет автоматически включать запросы в ваш исполняемый файл. Вы можете использовать следующую команду для принудительного включения запросов:

Вы можете указать это несколько раз в своей команде сборки, по одному разу для каждого скрытого импорта.

—add-data и —add-binary — вставить в вашу сборку дополнительные данные или двоичные файлы.

Это полезно, если вы хотите объединить файлы конфигурации, примеры или другие данные, не связанные с кодом. Пример этого вы увидите позже, если будете следить за проектом чтения каналов.

—exclude-module — исключите некоторые модули из вашего исполняемого файла

Это полезно для исключения требований только для разработчиков, таких как среды тестирования. Это отличный способ сделать артефакт, который вы даете пользователям, как можно меньше. Например, если вы используете pytest, вы можете исключить это из своего исполняемого файла:

-w — избегайте автоматического открытия окна консоли для ведения журнала стандартного вывода

Это полезно только в том случае, если вы создаете приложение с графическим интерфейсом. Это помогает скрыть детали реализации, позволяя пользователям никогда не видеть терминал.

Подобно опции —onefile, -w не принимает аргументов:

.spec файл

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

Поскольку это обычный скрипт Python, вы можете делать в нем практически все, что угодно. Вы можете обратиться к официальной документации файла спецификации PyInstaller для получения дополнительной информации об этом API.

Тестирование нового исполняемого файла ↑

Лучший способ протестировать ваш новый исполняемый файл — на новой машине. Новая машина должна иметь ту же ОС, что и ваша машина сборки. В идеале эта машина должна быть максимально похожа на то, что используют ваши пользователи. Это не всегда возможно, поэтому лучше всего провести тестирование на своей машине.

Ключ заключается в том, чтобы запустить полученный исполняемый файл без активации вашей среды разработки. Это означает запуск без virtualenv, conda или любой другой среды, которая может получить доступ к вашей установке Python. Помните, что одна из основных целей исполняемого файла, созданного PyInstaller, состоит в том, чтобы пользователям не нужно было ничего устанавливать на их машинах.

Взяв пример с программы чтения каналов, вы заметите, что запустить исполняемый файл cli по умолчанию в папке dist/cli не удается. К счастью, ошибка указывает на проблему:

Для пакета importlib_resources требуется файл version.txt. Вы можете добавить этот файл в сборку с помощью параметра —add-data. Вот пример того, как добавить необходимый файл version.txt:

Эта команда указывает PyInstaller включить файл version.txt в папку importlib_resources в новую папку в вашей сборке с именем importlib_resources.

Примечание. В командах pyinstaller используется символ \, чтобы упростить чтение команды. Вы можете опустить \ при выполнении команд самостоятельно или скопировать и вставить команды как-ниже при условии, что вы используете те же пути.

Вам нужно изменить путь в приведенной выше команде, чтобы он соответствовал тому месту, где вы установили зависимости программы чтения каналов.

Теперь запуск нового исполняемого файла приведет к новой ошибке, связанной с файлом config.cfg.

Этот файл требуется для проекта чтения каналов, поэтому обязательно включите его в свою сборку:

Опять же, вам нужно будет скорректировать путь к файлу в зависимости от того, где у вас находится проект программы чтения каналов.

На этом этапе у вас должен быть рабочий исполняемый файл, который можно передавать напрямую пользователям!

Отладка исполняемых файлов PyInstaller ↑

Как вы видели выше, вы можете столкнуться с проблемами при запуске исполняемого файла. В зависимости от сложности вашего проекта исправления могут быть такими простыми, как включение файлов данных, таких как пример программы чтения каналов. Однако иногда требуется больше методов отладки.

Ниже приведены несколько распространенных стратегий, которые не указаны в определенном порядке.Часто одна из этих стратегий или их комбинация приводит к прорыву в сложных сеансах отладки.

Используйте терминал ↑

Сначала попробуйте запустить исполняемый файл из терминала, чтобы увидеть весь вывод.

Не забудьте удалить флаг -w build, чтобы увидеть весь стандартный вывод в окне консоли. Часто вы увидите исключения ImportError, если зависимость отсутствует.

Файлы отладки ↑

Проверьте файл build/cli/warn-cli.txt на наличие проблем. PyInstaller создает множество выходных данных, чтобы помочь вам понять, что именно он создает. Копание в папке build/ — отличное место для начала.

Сборки одного каталога ↑

Используйте режим распространения —onedir для создания папки распространения вместо одного исполняемого файла. Опять же, это режим по умолчанию. Сборка с помощью —onedir дает вам возможность проверить все включенные зависимости вместо того, чтобы все было скрыто в одном исполняемом файле.

—onedir полезен для отладки, но —onefile обычно легче понять пользователям. После отладки вы можете переключиться в режим —onefile, чтобы упростить распространение.

Дополнительные параметры интерфейса командной строки ↑

PyInstaller также имеет параметры для управления объемом информации, печатаемой в процессе сборки. Перестройте исполняемый файл с параметром —log-level=DEBUG в PyInstaller и просмотрите вывод.

PyInstaller создаст много вывода при увеличении детализации с помощью —log-level=DEBUG. Полезно сохранить этот вывод в файл, к которому вы можете обратиться позже, вместо того, чтобы прокручивать его в Терминале. Для этого вы можете использовать функцию перенаправления вашей оболочки. Вот пример:

Используя указанную выше команду, вы получите файл build.txt, содержащий множество дополнительных сообщений DEBUG.

Примечание. Стандартного перенаправления с помощью> недостаточно. PyInstaller печатает в потоке stderr, а не stdout. Это означает, что вам нужно перенаправить поток stderr в файл, что можно сделать с помощью 2, как в предыдущей команде.

Вот пример того, как может выглядеть ваш файл build.txt:

В этом файле будет много подробной информации о том, что было включено в вашу сборку, почему что-то не было включено и как был упакован исполняемый файл.

Вы также можете перестроить свой исполняемый файл с помощью параметра —debug в дополнение к параметру —log-level для получения дополнительной информации.

Примечание: -y и -Параметры clean полезны при перестройке, особенно при первоначальной настройке сборок или при сборке с непрерывной интеграцией. Эти параметры удаляют старые сборки и исключают необходимость ввода данных пользователем в процессе сборки.

Дополнительные документы PyInstaller ↑

PyInstaller GitHub Wiki содержит множество полезных ссылок и советов по отладке. В первую очередь это разделы о том, как убедиться, что все упаковано правильно, и что делать, если что-то пойдет не так.

Помощь в обнаружении зависимостей ↑

Наиболее частая проблема, с которой вы столкнетесь, — это исключения ImportError, если PyInstaller не может правильно определить все ваши зависимости. Как упоминалось ранее, это может произойти, если вы используете __import__() , импорт внутри функций или другие типы скрытого импорта.

Многие из этих типов проблем можно решить с помощью —hidden-import параметр CLI PyInstaller. Это указывает PyInstaller включить модуль или пакет, даже если он не обнаруживает их автоматически. Это самый простой способ обойти множество магических действий динамического импорта в вашем приложении.

Другой способ обойти проблемы — файлы перехвата. Эти файлы содержат дополнительную информацию, которая поможет PyInstaller упаковать зависимость. Вы можете написать свои собственные хуки и указать PyInstaller использовать их с параметром CLI —additional-hooks-dir.

Файлы ловушек — это то, как сам PyInstaller работает внутри, поэтому вы можете найти множество примеров файлов ловушек в исходном коде PyInstaller.

Ограничения ↑

PyInstaller невероятно мощный, но у него есть некоторые ограничения. Некоторые из ограничений обсуждались ранее: скрытый импорт и относительный импорт в сценариях точки входа.

PyInstaller поддерживает создание исполняемых файлов для Windows, Linux и macOS, но не может выполнять Кросс-компилятор એ . Следовательно,вы не можете создать исполняемый файл, предназначенный для одной операционной системы, из другой операционной системы. Итак, чтобы распространять исполняемые файлы для нескольких типов ОС, вам понадобится машина сборки для каждой поддерживаемой ОС.

В связи с ограничением кросс-компиляции,полезно знать, что PyInstaller технически не объединяет абсолютно все, что нужно вашему приложению для работы. Ваш исполняемый файл по-прежнему зависит от пользовательской glibc એ . Как правило, вы можете обойти ограничение glibc એ , опираясь на самую старую версию каждой ОС, на которую вы собираетесь ориентироваться.

Например,если вы хотите нацелиться на широкий спектр машин Linux, вы можете использовать более старую версию CentOS. Это обеспечит совместимость с большинством версий новее, чем та, на которой вы построили. Это та же стратегия, которая описана в PEP 0513, и это то, что PyPA рекомендует для создания совместимых колес.

Фактически,Возможно, вы захотите изучить использование образа докера manylinux PyPA для вашей среды сборки Linux. Вы можете начать с базового образа, затем установить PyInstaller вместе со всеми вашими зависимостями и получить образ сборки, поддерживающий большинство вариантов Linux.

Заключение ↑

PyInstaller может помочь избавиться от необходимости в сложных установочных документах. Вместо этого ваши пользователи могут просто запустить ваш исполняемый файл, чтобы начать работу как можно быстрее. Рабочий процесс PyInstaller можно резюмировать, выполнив следующие действия:

1. Создайте сценарий точки входа, который вызывает вашу основную функцию.
2. Установите PyInstaller.
3. Запустите PyInstaller на своей точке входа.
4. Протестируйте свой новый исполняемый файл.
5. Отправьте полученную папку dist/ пользователям.

Ваши пользователи не должны знать, какую версию Python вы использовали или что ваше приложение вообще использует Python!