Nuitka: почему однофайловый бинарник падает с «No module named…» и как это исправить

Почему бинарник Nuitka на Linux Mint 22 падает с «No module named…»: модуль cryptography не установлен в venv. Решение — установить зависимость и пересобрать.

Упаковка Python-скрипта в единый исполняемый файл кажется простой — пока какая‑нибудь зависимость незаметно не выпадает. Типичный сценарий: сборка однофайлового бинарника с Nuitka на Linux Mint 22 внутри виртуального окружения проходит успешно, но при запуске исполняемый файл падает с ошибкой «No module named …». Используются Python 3.12.3 и Nuitka 2.7.2; компиляция идет без видимых проблем и создает .bin вместе с папками сборки. Ошибка возникает в тот момент, когда программа доходит до второго import.

Минимальный пример, воспроизводящий сбой

Заголовок скрипта выглядит так; сбой происходит на втором import:

#!/usr/bin/python3
from pathlib import Path as Pth
from cryptography.fernet import Fernet as FernetCipher
import subprocess as sh
import math as maths
from math import gcd as gcd_fn

Шаги сборки и запуска простые:

python3 -m nuitka --standalone --follow-imports --python-flag=no_site --onefile myscript.py
./myscript.bin

Бинарник стартует и сразу прерывается с «No module named …» ровно там, где импорт cryptography должен был пройти.

Что на самом деле происходит

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

Это не особенность Nuitka как инструмента. При аналогичных условиях то же самое наблюдается с PyInstaller или cx_Freeze: если модуля нет в виртуальном окружении, из которого вы собираете, он не будет включен в пакет.

Решение: установить недостающую зависимость в venv и пересобрать

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

pip install cryptography
python3 -m nuitka --standalone --follow-imports --python-flag=no_site --onefile myscript.py
./myscript.bin

Почему стоит держать это в уме

Инструменты сборки исполняемых файлов опираются только на то, что доступно в окружении сборки. Если виртуальное окружение не отражает реальные потребности вашего скрипта, ошибка не проявится на этапе компиляции; она всплывет при запуске бинарника, когда начнут импортироваться модули. Эта особенность помогает избежать загадочных «No module named …», которые вроде бы противоречат успешному запуску скрипта системным интерпретатором.

Итоги

При сборке однофайлового автономного исполняемого файла с Nuitka на Linux Mint 22 внутри виртуального окружения убедитесь, что все сторонние модули, которые импортирует ваш код, установлены в этом же окружении. В приведенном примере установка cryptography в venv и пересборка решили проблему. Версии Python и Nuitka совпадали (Python 3.12.3 и Nuitka 2.7.2), так что дело было не в несовместимости, а в отсутствии нужного пакета в окружении сборки.

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