Hyprland: типичные ошибки и как их исправить

Коротко о главном

Hyprland не является рабочим столом в привычном смысле: это композитор, который сам управляет окнами и отрисовкой. Он предлагает динамическую раскладку, плавные анимации и богатую систему правил для окон. Настройка ведётся через hyprland.conf, что удобно для версионирования конфигурации. Разберём установку, мониторы, горячие клавиши, панель и порталы.

Hyprland даёт современный внешний вид и высокую производительность на Wayland. Динамическая тайлинговая раскладка экономит время при работе с терминалами и редакторами. Плагины и скрипты позволяют собрать окружение под себя. Конфигурация в текстовом виде легко переносится между машинами.

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

Почему это происходит

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

Типичные ошибки

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

1. После входа нет курсора мыши

Проверьте, что установлен пакет с курсорами и переменная XCURSOR_THEME задана. На некоторых драйверах помогает смена бэкенда или обновление Mesa.

2. Hyprland падает после обновления

Откатите версию пакета и пересоберите плагины под неё. Проверьте журнал сессии, чтобы найти несовместимый плагин.

3. Не работает демонстрация экрана

Установите xdg-desktop-portal-hyprland и убедитесь, что PipeWire запущен. Перезапустите портал после обновления композитора.

4. Не переключается раскладка клавиатуры

Задайте несколько раскладок в input и назначьте команду переключения через hyprctl switchxkblayout. Проверьте, что не конфликтует другой обработчик ввода.

Как настроить правильно

Правильная последовательность проста: проверить версию и зависимости, сделать резервную копию конфигурации, внести минимальное изменение, проверить логи и только потом двигаться дальше.

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install git meson ninja-build wayland-protocols libwayland-dev
# затем сборка из исходников по документации проекта

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install hyprland

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S hyprland

1. Установка и первый запуск

Проверьте, что система работает на Wayland и установлен свежий драйвер видеокарты. В Debian стабильной ветки пакета может не быть, тогда собирайте из исходников. После установки выберите сессию Hyprland в менеджере входа или запустите из tty.

Hyprland --version
ls /usr/share/wayland-sessions/

2. Настройка мониторов

Строка monitor задаёт разрешение, частоту и масштаб для каждого вывода. Пустое имя с правилом auto подходит для одного экрана. Для нескольких мониторов укажите идентификаторы из hyprctl monitors.

hyprctl monitors
hyprctl keyword monitor HDMI-A-1,1920x1080@144,0x0,1

3. Горячие клавиши и окна

Клавиши задаются директивой bind, а режимы и перемещение окон — отдельными командами. Используйте SUPER как основной модификатор, чтобы не конфликтовать с приложениями. Проверить синтаксис можно через hyprctl reload.

bind = $mod, Q, killactive
bind = $mod, 1, workspace, 1
bind = $mod SHIFT, 1, movetoworkspace, 1
hyprctl reload

4. Панель и лаунчер

Hyprland не включает панель, её ставят отдельно: waybar, ags или другой проект. Лаунчер вроде wofi или rofi запускается по горячей клавише. Оба инструмента настраиваются своими файлами.

sudo pacman -S waybar wofi
waybar &
wofi --show drun

Рабочий конфиг

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

monitor=,preferred,auto,1
$mod = SUPER
exec-once = waybar &
exec-once = hyprpaper
input {
    kb_layout = us,ru
    follow_mouse = 1
}
general {
    gaps_in = 5
    gaps_out = 10
    border_size = 2
}
bind = $mod, Return, exec, kitty

Практические советы

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

Совет 1. Храните конфигурацию в git: эксперименты с раскладкой удобно откатыват

Храните конфигурацию в git: эксперименты с раскладкой удобно откатывать.

Совет 2. Проверяйте синтаксис через hyprctl reload, а не перезагрузкой всей сес

Проверяйте синтаксис через hyprctl reload, а не перезагрузкой всей сессии.

Совет 3. Для скриншотов используйте grim и slurp, они хорошо работают с wlroots

Для скриншотов используйте grim и slurp, они хорошо работают с wlroots-композиторами.

Совет 4. Не запускайте два композитора одновременно: это приводит к конфликту з

Не запускайте два композитора одновременно: это приводит к конфликту за устройства ввода.

Профилактика

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

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

Итог

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