راهنمای جامع نصب و پیکربندی Hyprland در Arch Linux

راهنمای جامع نصب و پیکربندی Hyprland در Arch Linux

Hyprland یک کامپوزیتور مستقل و پویا (Dynamic Tiling) برای Wayland است که به خاطر انیمیشن‌های نرم، پنجره‌های تب‌دار، گوشه‌های گرد و افکت شفافیت شناخته می‌شود. از نسخهٔ 0.55 به بعد، زبان پیکربندی Hyprland از hyprlang به Lua تغییر کرده و فایل قدیمی hyprland.conf منسوخ شده است. این مقاله نصب و پیکربندی اولیهٔ آن را در Arch Linux آموزش می‌دهد.

---

پیش‌نیازها و هشدارهای مهم

توزیع و سخت‌افزار

Hyprland به طور رسمی روی Arch Linux و NixOS تست و پشتیبانی می‌شود. استفاده از آن روی کارت‌های گرافیک NVIDIA به طور رسمی پشتیبانی نمی‌شود و ممکن است با باگ‌هایی مانند عدم ورود، پرش پنجره‌ها یا مصرف بالای CPU مواجه شوید. پیش از اجرا، صفحهٔ مخصوص NVIDIA در ویکی رسمی Hyprland را مطالعه کنید.

Polkit

حتماً بستهٔ polkit را نصب کنید یا سرویس seatd.service را فعال نمایید. نبود آن باعث عدم راه‌اندازی Hyprland می‌شود.

sudo pacman -S polkit

ماشین مجازی

کاربران VMware یا VirtualBox ممکن است برای اجرای صحیح Hyprland نیاز به فعال‌سازی شتاب سه‌بعدی (3D Acceleration) داشته باشند.

---

نصب Hyprland

نصب از مخازن رسمی (توصیه‌شده)

sudo pacman -S hyprland

همچنین بستهٔ پورتال را برای اشتراک‌گذاری صفحه نصب کنید:

sudo pacman -S xdg-desktop-portal-hyprland

نصب از AUR (نسخهٔ Git)

اگر به آخرین ویژگی‌ها نیاز دارید:

yay -S hyprland-git

برای دریافت تمام اجزای اکوسیستم Hypr (نسخهٔ Git) می‌توانید از hyprland-meta-git استفاده کنید:

yay -S hyprland-meta-git

هشدار: استفاده از نسخه‌های -git می‌تواند منجر به خطاهای .so not found شود؛ زیرا هر بار که یک وابستگی مستقیم مانند hyprutils به‌روزرسانی ABI داشته باشد، باید Hyprland و ابزارهای وابسته دوباره کامپایل شوند.

---

راه‌اندازی Hyprland

Hyprland را می‌توانید مستقیماً از ترمینال (TTY) اجرا کنید:

start-hyprland

هرگز از sudo برای اجرای Hyprland استفاده نکنید.

---

پیکربندی با Lua

محل فایل پیکربندی

مسیر پیش‌فرض فایل پیکربندی:

~/.config/hypr/hyprland.lua

اگر فایل وجود نداشته باشد، Hyprland به طور خودکار یک پیکربندی نمونه ایجاد می‌کند. برای حذف بنر هشدار تولید خودکار، خط hl.config({ autogenerated = true }) را از فایل حذف کنید.

پس از هر تغییر، پیکربندی به طور خودکار بارگذاری می‌شود. برای بارگذاری دستی:

hyprctl reload

تنظیم صفحه‌کلید (Keymap)

به طور پیش‌فرض چیدمان us استفاده می‌شود. برای تغییر به آلمانی Colemak:

-- ~/.config/hypr/hyprland.lua
hl.config({
    input = {
        kb_layout = "de",
        kb_variant = "colemak",
    }
})

تنظیم نرخ تکرار کلید

hl.config({
    input = {
        repeat_rate = 25,
        repeat_delay = 600,
    }
})

تنظیم مانیتور

ابتدا نام مانیتور را پیدا کنید:

hyprctl monitors all

سپس در فایل monitors.lua یا هر فایل Lua که با require بارگذاری می‌کنید:

hl.monitor({
    output = "eDP-1",
    mode = "1920x1080@60",
    position = "0x0",
    scale = 1
})

hl.monitor({
    output = "HDMI-A-1",
    mode = "2560x1440@144",
    position = "1920x0",
    scale = 1
})

کلیدهای میانبر (Keybindings)

در فایل bindings.lua:

-- باز کردن ترمینال با SUPER + Q
hl.bind("SUPER + Q", hl.dsp.exec_cmd("kitty"))

-- تمام‌صفحه کردن پنجره با SUPER + F
hl.bind("SUPER + F", hl.dsp.window.fullscreen())

-- اجرای لانچر برنامه‌ها
hl.bind("SUPER + R", hl.dsp.exec_cmd("wofi --show drun"))

اجرای خودکار برنامه‌ها در استارتاپ

در فایل autostart.lua:

hl.on("hyprland.start", function()
    hl.exec_cmd("waybar")
    hl.exec_cmd("hyprpaper")
end)

تقسیم پیکربندی به چند فایل (Require)

Hyprland توصیه می‌کند پیکربندی را به ماژول‌های جداگانه تقسیم کنید تا خطا در یک فایل، اجرای بقیه را متوقف نکند.

در فایل hyprland.lua:

require("awesomeconf.animation")
require("awesomeconf.keybinds")
require("./lua/*")

اگر از require برای ماژولی استفاده کنید که وجود ندارد، اجرای کل فایل اصلی متوقف می‌شود. برای جلوگیری از این مشکل از pcall استفاده کنید:

local status, value = pcall(require, "maybe-nonexistent")

---

اکوسیستم Hyprland و ابزارهای ضروری

Hyprland یک محیط دسکتاپ کامل نیست و باید ابزارهای موردنیاز خود را انتخاب کنید. تیم رسمی مجموعه‌ای از ابزارهای اختصاصی را توسعه داده است:

| ابزار | عملکرد | دستور نصب |
|------|------|----------|
| Hyprpaper | مدیریت تصویر زمینه | sudo pacman -S hyprpaper |
| Hypridle | مدیریت بی‌کاری | sudo pacman -S hypridle |
| Hyprlock | قفل صفحه | sudo pacman -S hyprlock |
| Hyprpicker | انتخاب رنگ | sudo pacman -S hyprpicker |
| Hyprcursor | مدیریت نشانگر ماوس | sudo pacman -S hyprcursor |

سایر ابزارهای پیشنهادی

• ترمینال: kitty
• نوار وضعیت: waybar
• لانچر: wofi
• روشنایی صفحه: brightnessctl

sudo pacman -S kitty waybar wofi brightnessctl

---

عیب‌یابی

متن‌های مربعی پس از نصب تازه

Hyprland به فونت‌های sans-serif وابسته است، اما بستهٔ آن این وابستگی را به همراه ندارد. اگر صفحهٔ خوش‌آمدگویی با مربع‌های نامفهوم نمایش داده شد، فونت مناسب را نصب کنید:

sudo pacman -S ttf-dejavu

بررسی خطاهای پیکربندی

پس از هر تغییر در پیکربندی Lua، وضعیت را اعتبارسنجی کنید:

hyprctl reload
hyprctl configerrors

اگر خطایی گزارش شد، آن را برطرف کنید تا خروجی تمیز شود.

مشاهده اطلاعات پنجره‌ها

hyprctl clients
hyprctl activewindow

لاگ‌ها

مسیر لاگ‌ها:

/tmp/hypr/[INSTANCE_SIGNATURE]/hyprland.log

---

تصاویر و منابع بصری

برای مشاهدهٔ نمونه‌های واقعی از ظاهر Hyprland، از مخازن زیر بازدید کنید:

• مجموعهٔ والپیپرهای Hyprland:

https://github.com/Ajaymanikandan0x/hyprland_wallpapers

• نمونهٔ پیکربندی Hyprland + Waybar (Rose Pine):

تصاویر در انجمن BTT با تم Rose Pine و والپیپر Forest موجود است.

• نمونهٔ پیکربندی Pywal:

https://github.com/Niranj-S/Hyprland-Rice-Pywal

برای تهیهٔ اسکرین‌شات از دسکتاپ خودتان:

grim ~/Pictures/hyprland-setup.png

---

لینک‌های مرتبط

• ویکی رسمی Hyprland: https://wiki.hypr.land/
• ArchWiki Hyprland: https://wiki.archlinux.org/***/Hyprland
• مخزن Awesome-Hyprland (منابع جامعه): https://github.com/hyprland-community/awesome-hyprland
• صفحهٔ NVIDIA در ویکی Hyprland: https://wiki.hypr.land/Nvidia

---

این مقاله بر اساس مستندات رسمی Hyprland (نسخهٔ 0.56) و ArchWiki گردآوری شده و برای جامعهٔ ARCHIHA تهیه شده است. آخرین به‌روزرسانی: نوامبر 2026.