В официальной записи PyInstaller указана версия 6.22.3 — ориентируйтесь на неё, если именно эту версию требует ваш проект, и фиксируйте её в окружении сборки (история изменений PyInstaller). Чтобы получить приложение для macOS, запускайте PyInstaller в macOS: сначала соберите вариант onedir, проверьте зависимости и данные, и только после этого решайте, нужен ли onefile. Успешный запуск не доказывает воспроизводимость научного результата, а готовый пакет ещё не означает, что выполнены требования внешнего распространения.
Эта инструкция для аспирантов и докторантов, передающих Python-анализ руководителю или соавтору на Mac. Она также пригодится разработчикам научных GUI-программ с данными и нативными зависимостями. Технические специалисты вузов найдут здесь последовательность сборки и критерии приёмки для рабочей группы.
До сборки: платформа, получатель и копия проекта
PyInstaller не превращает сборку, сделанную в Windows или Linux, в готовое приложение для macOS. Для разных целевых операционных систем нужны соответствующие среды сборки: PyInstaller описывает создание пакета как процесс для целевой платформы, а не как универсальную кросс-компиляцию (официальное описание платформ и сборки). Поэтому сначала найдите доступ к Mac с macOS, а затем собирайте и проверяйте приложение там.
Можно ли прямо в Windows собрать приложение PyInstaller для Mac? Нет — не считайте Windows-сборку приложением для macOS. Если локального Mac нет, перенесите проект на доступную среду macOS и выполняйте там установку зависимостей, сборку и запуск. Если задача ограничивается проверкой логики Python, Windows может быть полезен для разработки; он не заменяет проверку именно macOS-артефакта.
До изменений сохраните исходный проект и создайте отдельную рабочую копию для сборки. Это позволяет отличить ошибку упаковки от случайной правки кода и повторить сборку, не восстанавливая файлы вручную. Для копии запишите:
- версию Python и точную версию PyInstaller;
- способ установки зависимостей и их зафиксированный список;
- архитектуру Mac, на котором выполняется сборка;
- команду сборки или используемый файл
.spec; - перечень входных файлов, конфигураций, шаблонов и ожидаемых результатов.
Подготовка проекта: зависимости и исследовательские ресурсы
Создайте для упаковки чистое окружение проекта. Например, из каталога рабочей копии можно выполнить:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "pyinstaller==6.22.3"Затем установите зависимости проекта тем способом, который предусмотрен репозиторием: из зафиксированного файла требований, lock-файла или другой принятой в группе спецификации. Не подменяйте его установкой «последних версий всего»: если библиотека изменилась между запуском исходного проекта и сборкой, причины отличий будет трудно локализовать. Проверьте, что исходный скрипт запускается в этом же окружении до упаковки. Иначе вы не поймёте, появилась ли ошибка из-за PyInstaller или проект не работал уже до сборки.
Просмотрите импорты и выясните, какие файлы приложение ищет во время выполнения. В научном проекте это часто не только код: рядом могут находиться таблицы коэффициентов, изображения, модели, шаблоны отчётов, конфигурации и примеры входных данных. Разделите их на три группы:
- Неизменяемые ресурсы приложения — файлы, без которых программа не может выполнить свою задачу и которые должны поставляться вместе с ней.
- Входные данные пользователя — выбираемые исследователем файлы, которые нельзя жёстко привязывать к месту установки приложения.
- Результаты и настройки — создаваемые или изменяемые файлы, для которых нужно заранее определить допустимое место сохранения.
.spec в [документации PyInstaller](https://pyinstaller.org/en/stable/spec-files.html).
Временный успешный запуск из каталога разработки не подтверждает правильность путей. Перед упаковкой проверьте приложение из другой рабочей папки и убедитесь, что пользователь выбирает входные файлы через интерфейс или явно заданную конфигурацию.
Первая сборка: диагностируемый вариант onedir
Сначала упакуйте проект в режиме onedir. Каталоговый вариант удобнее для диагностики: его содержимое можно осмотреть и выяснить, попали ли в сборку нужные компоненты. В документации PyInstaller режимы one-folder и one-file описаны отдельно; onefile извлекает компоненты во временный каталог при запуске, что меняет поведение пакета и требует отдельной проверки (описание режимов сборки).
После проверки исходного приложения установите и запустите PyInstaller в macOS. Для обычного GUI-скрипта начальную команду можно оформить так:
python -m PyInstaller --noconfirm --clean --onedir --windowed --name LabTool main.pyЗамените main.py на точку входа вашего проекта, а LabTool — на принятое в группе имя. Опции командной строки, включая выбор режима сборки и поведение окна консоли, сверяйте с руководством PyInstaller по параметрам запуска. Если проект требует дополнительной настройки файлов или скрытых импортов, храните её в файле .spec, чтобы команда и состав сборки были воспроизводимыми.
Проверьте журнал сборки и сам результат. Импорт, который выполняется динамически, может не обнаружиться при анализе кода; отдельные пакеты используют hooks для настройки сбора зависимостей. В таком случае сначала найдите воспроизводимый сбой, а затем проверьте применимость официального механизма hooks PyInstaller. Не добавляйте случайные каталоги целиком и не объявляйте все возможные импорты скрытыми без диагностики: это затрудняет аудит того, что именно оказалось в приложении.
Если модуль или библиотека отсутствует, зафиксируйте точную команду, сообщение об ошибке, версию окружения и минимальный способ повторить проблему. Исправляйте по одному пункту: добавьте нужный импорт или ресурс, повторите чистую сборку и убедитесь, что исходный сценарий остаётся рабочим. Один успешный старт — только проверка запуска, а не подтверждение того, что научный анализ завершился корректно.
Проверка из Finder: GUI, пути и результаты
Запустите приложение именно так, как это будет делать получатель: откройте его из Finder, а не только из активированного виртуального окружения в терминале. Для Python-программы с GUI проверьте элементы интерфейса, выбор файлов и сообщения об ошибках. При отсутствии консольного окна ошибки могут быть менее заметны, поэтому предусмотрите логирование в доступное место или понятный вывод для пользователя.
Для первого прохода используйте заранее подготовленный обезличенный набор данных. Сравните исходную программу и собранное приложение по одному и тому же сценарию:
- загружается ли тот же входной файл и распознаются ли его формат и кодировка;
- совпадают ли ключевые численные результаты с результатами исходного проекта в пределах критериев, принятых для этого анализа;
- создаётся ли выходной файл там, где ожидает пользователь;
- остаются ли отчёт, график или журнал после закрытия приложения;
- понятны ли сообщения, если файл отсутствует или имеет неверный формат.
Что делать, если после сборки программа не находит файлы проекта? Сначала выясните, какой именно файл отсутствует и относится ли он к встроенному ресурсу, входным данным или результатам. Затем проверьте, указан ли ресурс в конфигурации сборки и использует ли код правильный путь при запуске из Finder. После исправления повторите сборку и тест из другой рабочей папки; ручное копирование файла рядом с приложением можно использовать для диагностики, но не считать доказательством, что пакет готов к передаче.
Выбор формата и оценка маршрута
После проверки onedir выбирайте способ поставки по условиям получателя, а не по принципу «один файл всегда удобнее». Оценка ниже — инженерная рекомендация для этапа выбора, а не результат сравнительного теста производительности.
| Критерий | onedir — каталог приложения | onefile — единый запускаемый пакет |
|---|---|---|
| Поиск недостающих компонентов | Оценка для диагностики: высокая — проще осматривать состав каталога | Оценка для диагностики: ниже — компоненты упакованы в единый файл |
| Передача пользователю | Подходит, если можно передать каталог целиком | Удобен, когда получателю важен один файл |
| Внешние ресурсы и изменяемые данные | Легче отделить файлы приложения от пользовательских данных | Нужно особенно тщательно определить, где находятся изменяемые файлы |
| Повторная проверка | Обязательна после изменения ресурсов и конфигурации | Нужна повторная проверка после перехода с onedir |
| Решение для первой сборки | Предпочтительный диагностический этап | Рассматривать после успешной проверки onedir |
Как выбрать между onedir и onefile?
- Если вы ещё выясняете, каких библиотек или ресурсов не хватает, оставьте onedir и исправьте сборку.
- Если получатель может принимать каталог целиком, а проверяемость состава важна для группы, передавайте onedir.
- Если передача одного файла — явное ограничение, сначала завершите приёмку onedir, затем соберите onefile и повторите тесты с теми же входами.
- Если приложение записывает настройки или результаты, не помещайте изменяемые данные в расположение ресурсов приложения; задайте отдельное место сохранения и проверьте, что оно доступно пользователю.
.spec, чтобы коллега мог понять, какой вариант был передан и на каких условиях он проверялся.
Передача группе: воспроизводимость и распространение
Перед передачей используйте другую копию проекта или отдельную учётную запись целевого Mac, если такая проверка доступна. Установите, что приложение запускается без активированного окружения разработчика и без случайных файлов, оставшихся в каталоге сборки. Проведите представительный анализ, сохраните результат, а затем сравните его с заранее установленным эталоном. Передайте не только приложение, но и краткую инструкцию: поддерживаемый сценарий, способ выбора данных, место выходных файлов, известные ограничения и контакт для сообщения об ошибке.
Разделяйте три результата проверки:
- Приложение запускается. macOS открывает пакет, интерфейс доступен, а тестовый вход не приводит к немедленному сбою.
- Научный результат воспроизводим. Задокументированные входы и параметры дают ожидаемые результаты в пределах критериев вашего метода; версии и способ сборки сохранены.
- Пакет готов к распространению. Проверены применимые требования подписи, нотариального заверения и выбранного способа распространения.
Нужны ли подпись и нотариальное заверение? Это зависит от аудитории и способа распространения. Для требований macOS к распространению сверяйтесь с актуальной документацией Apple о подписании и распространении программного обеспечения. Не считайте внутренний тест готовой процедурой для публичной поставки и не обходите системные проверки безопасности. Если приложение предназначено только для ограниченной внутренней проверки, документируйте этот контекст; если его будут получать внешние пользователи, отдельно проверьте актуальные требования Apple и подготовьте соответствующий процесс выпуска.
Условия принятия решения
Используйте этот список перед передачей, чтобы выбрать следующий шаг:
- Если у вас нет Mac для сборки, сначала получите доступ к macOS и перенесите туда проект с разрешёнными для передачи тестовыми данными. Сборка на Windows не заменяет этот этап.
- Если чистая сборка onedir не проходит тест запуска, не переходите к onefile; найдите отсутствующий импорт, библиотеку или ресурс и воспроизведите исправление.
- Если запуск успешен, но результат отличается от исходного проекта, приостановите передачу. Сверьте входные данные, параметры и зависимости, затем отделите расхождение научной логики от сбоя упаковки.
- Если GUI, входы и результаты проверены, но приложение должно получить внешних пользователей, не объявляйте его готовым к выпуску до отдельной проверки требований подписи и распространения Apple.
- Если группе нужно только внутреннее воспроизведение анализа, сохраняйте вместе с приложением инструкции, входной тестовый пример, ожидаемый результат и сведения о сборке; это делает повторную проверку содержательной, а не формальной.
Когда использовать удалённую macOS-среду
Если у вас уже есть подходящий Mac и сборка редкая, использовать его может быть проще, чем настраивать удалённый процесс. Если проект долго сопровождается, нужен регулярный тест на разных Mac или требуются физические интерфейсы и периферия, заранее сравните покупку устройства, ресурсы лаборатории и удалённую среду: постоянная высокая нагрузка и непосредственный доступ к оборудованию могут сделать аренду неподходящей.
Но если рабочая среда группы ограничена Windows или Linux, у такого маршрута есть конкретные недостатки: целевой пакет macOS нельзя подтвердить без сборки на macOS; повторение теста зависит от доступности подходящего Mac; передача проекта между устройствами добавляет риск неверно скопировать ресурсы или конфигурацию. Временная аренда удалённого Mac у MACGPU может быть удобна для ограниченной сборки и повторной проверки, если вам подходит удалённый доступ и ваши правила обработки данных разрешают такую работу. Перед переносом проекта проверьте границы данных и порядок доступа; сведения о руководстве по Mac и вариантах аренды помогут оценить среду до начала сборки.
Для PyInstaller 6.22.3 на Mac надёжная последовательность остаётся такой: macOS-сборка, диагностика в onedir, проверка ресурсов и результатов, затем — при необходимости — переход к onefile и отдельная оценка требований распространения. Начинайте с самого короткого воспроизводимого теста, который подтверждает не только запуск Python-программы, но и ожидаемый научный результат.