При запуске linuxdeployqt с готовым бинарным файлом утилита часто завершается ошибкой вида «cannot find ldd output» или предупреждением о несовместимой версии glibc — и именно с этим сталкивается большинство разработчиков при первой попытке собрать переносимый пакет. Причина почти всегда одна: инструмент запущен неправильно, без подготовленного окружения или на слишком новой системе сборки.
linuxdeployqt — это консольная утилита, которая автоматически собирает все зависимости Qt-приложения (библиотеки, плагины, QML-модули, переводы) в один каталог и при необходимости упаковывает результат в формат AppImage. Она избавляет от ручного копирования десятков файлов и позволяет распространять программу пользователям, у которых Qt не установлен.
Ниже разберём установку, базовые команды, полезные флаги и типовые ошибки — всё, что нужно, чтобы уверенно пользоваться инструментом на практике.
Установка linuxdeployqt
Проще всего взять готовую сборку в формате AppImage со страницы релизов проекта на GitHub. Скачанный файл нужно сделать исполняемым и желательно переименовать для удобства:
chmod +x linuxdeployqt-continuous-x86_64.AppImage
sudo mv linuxdeployqt-continuous-x86_64.AppImage /usr/local/bin/linuxdeployqt
После этого команда linuxdeployqt становится доступна из любого каталога. Проверить установку можно запуском с флагом -version — утилита выведет номер сборки и краткую справку.
⚠️ Внимание: linuxdeployqt принципиально отказывается работать от имени root. Если вы привыкли выполнять сборку через sudo, получите ошибку — запускайте утилиту от обычного пользователя.
Подготовка приложения к развёртыванию
Перед запуском linuxdeployqt приложение должно быть собрано в Release-режиме. Debug-сборки тащат отладочные библиотеки и заметно раздувают итоговый пакет, поэтому сначала выполните qmake или сборку через CMake с конфигурацией Release.
Ключевое требование — переменная окружения PATH должна указывать на тот экземпляр Qt, с которым собрано приложение. Если в системе несколько версий Qt, утилита возьмёт первую найденную, и зависимости могут не совпасть с бинарником. Проверьте, какой qmake виден в терминале:
which qmake
qmake -v
Также понадобится корректный .desktop-файл и иконка — они обязательны при создании AppImage и желательны для обычного каталога развёртывания. Файл desktop должен содержать корректные поля Name, Exec и Icon.
☑️ Подготовка к запуску linuxdeployqt
Базовое использование: основные команды
Самый простой сценарий — указать путь к бинарному файлу приложения. Утилита проанализирует его через ldd и скопирует недостающие библиотеки рядом с исполняемым файлом:
linuxdeployqt ./MyApp -verbose=1Для создания полноценного AppImage добавьте флаг -appimage и укажите desktop-файл:
linuxdeployqt ./MyApp.desktop -appimage -qmake=/path/to/qmakeЕсли приложение использует QML, без дополнительного флага плагины не попадут в пакет — укажите каталог с QML-исходниками через -qmldir:
linuxdeployqt ./MyApp -qmldir=/path/to/project/qml -appimageОсновные флаги, которые пригодятся чаще всего:
- 🔧
-appimage— собрать результат в формат AppImage; - 📦
-bundle-non-qt-libs— включить в пакет сторонние библиотеки, не относящиеся к Qt; - 🗂
-qmldir=<путь>— подтянуть QML-модули из указанного каталога; - 🔍
-verbose=2— подробный вывод, незаменим при отладке; - 🚫
-no-plugins— не копировать плагины Qt (редкий сценарий).
Выбор системы сборки и совместимость
Критичное правило linuxdeployqt: собирайте пакет на самой старой версии дистрибутива, на которой приложение должно работать. Бинарник, собранный на новой системе, требует свежую версию glibc и не запустится на старых дистрибутивах пользователей. Обратная совместимость — со старой системы на новую — обычно работает, прямая — нет.
На практике это означает, что для широкой аудитории сборку выполняют в контейнере Docker или на виртуальной машине со старым LTS-выпуском дистрибутива. Если собрать на свежей системе, linuxdeployqt может вообще отказаться упаковывать системные библиотеки, выдав предупреждение о слишком новой glibc.
Типичные ошибки и их решение
Разберём проблемы, с которыми чаще всего сталкиваются при работе с утилитой. Точный текст ошибок может отличаться в зависимости от версии, поэтому ориентируйтесь на смысл сообщения.
| Ошибка / симптом | Вероятная причина | Решение |
|---|---|---|
| Отказ запуска от root | Запуск через sudo | Выполнить от обычного пользователя |
| QML-элементы не найдены в пакете | Не указан -qmldir | Добавить флаг -qmldir с путём к QML |
| Предупреждение о версии glibc | Слишком новая система сборки | Собирать на старом дистрибутиве |
| Не найден qmake | Qt не в PATH | Указать -qmake=/путь/к/qmake |
| AppImage не создаётся | Нет корректного .desktop-файла | Проверить поля Name, Exec, Icon |
⚠️ Внимание: linuxdeployqt не упаковывает библиотеки, которые считает системными (например, libGL, libX11 и часть низкоуровневых зависимостей). Если приложение использует нестандартные сторонние библиотеки, проверьте итоговый пакет на чистой системе — иначе часть зависимостей может оказаться за бортом.
Почему часть библиотек не попадает в пакет
Внутри linuxdeployqt есть «чёрный список» библиотек, которые предполагаются присутствующими в любой целевой системе: ядерные компоненты, драйверы графического стека, базовые системные библиотеки. Упаковка этих файлов создала бы конфликты на чужих машинах, поэтому инструмент сознательно их пропускает. Если вашей программе нужна конкретная версия такой библиотеки, её придётся распространять отдельно или статически линковать.
Альтернативы и когда их стоит рассмотреть
linuxdeployqt — не единственный инструмент в этой нише, и в некоторых сценариях альтернативы удобнее. Проект развивается умеренно, поэтому для новых версий Qt (особенно Qt6) стоит проверить актуальную совместимость на странице репозитория.
Что можно использовать вместо или в дополнение:
- 🧰 linuxdeploy — более модульный инструмент с системой плагинов, включая плагин для Qt;
- 📦 appimagetool — низкоуровневая утилита для упаковки готового AppDir в AppImage;
- 🏗 Статическая сборка Qt — радикальный вариант, когда всё линкуется в один бинарник (требует учёта лицензионных условий Qt);
- 🐳 Сборка в Docker + ручная упаковка — максимальный контроль над составом пакета.
Выбор зависит от задачи: для быстрого результата с Qt5 linuxdeployqt остаётся самым простым путём, а для сложных CI/CD-конвейеров гибче связка linuxdeploy с плагинами.
Часто задаваемые вопросы
Работает ли linuxdeployqt с Qt6?
Поддержка Qt6 в linuxdeployqt ограничена и зависит от версии инструмента. Перед использованием проверьте актуальные issues и релизы проекта на GitHub. Для Qt6-проектов часто надёжнее использовать linuxdeploy с Qt-плагином или ручную упаковку.
Почему linuxdeployqt отказывается работать под root?
Это осознанное ограничение разработчиков: запуск от root создаёт файлы с неправильными правами внутри AppDir, что ломает пакет у конечных пользователей и несёт риски безопасности. Запускайте утилиту от обычного пользователя — для её работы повышенные привилегии не нужны.
Как проверить, что в пакет попали все зависимости?
Запустите готовый AppImage или бинарник из AppDir на системе без установленного Qt — в виртуальной машине или Docker-контейнере. Дополнительно можно выполнить ldd по бинарнику и убедиться, что пути разрешаются внутри каталога пакета, а не в системные библиотеки.
Чем AppImage отличается от обычного каталога с библиотеками?
AppImage — это один исполняемый файл-образ, который монтируется при запуске и содержит приложение со всеми зависимостями. Каталог (AppDir) — промежуточный вариант: его можно копировать и запускать, но распространять удобнее именно AppImage, так как пользователю достаточно скачать один файл и дать ему права на исполнение.
Можно ли использовать linuxdeployqt в CI/CD?
Да, инструмент хорошо подходит для автоматизации: все параметры передаются флагами командной строки. Главное — подобрать образ сборки с достаточно старой версией дистрибутива для совместимости и убедиться, что qmake нужной версии Qt доступен в PATH внутри конвейера.