Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AhmedSaadi0/NibrasShell/llms.txt

Use this file to discover all available pages before exploring further.

NibrasShell requires a Hyprland-based Wayland session and a few system-level dependencies before the shell can run. The automated installer — nibras_installer/main.py — handles dependency installation, file copying, theme extraction, font setup, and initial configuration in a single interactive script. It supports Arch Linux (and Arch-based distributions via yay), Fedora (and Nobara), and Void Linux out of the box. If you are on another distribution, you can follow the manual installation steps below.

​
System requirements

Before installing, make sure your system meets these requirements:
  • Hyprland — Wayland compositor and window manager
  • Quickshell — QML shell framework (installed by the script on supported distros)
  • Python 3.13 — Required for the installer and background scripts
  • yay — AUR helper (Arch only; must be installed before running the script)
  • A working Wayland session — X11 is not supported
  • Git — To clone the repository
The installer must not be run as root or with sudo. Run it as your normal user account.

​
Automated installation

The recommended way to install NibrasShell is with the interactive installer. It guides you through dependency installation, file setup, and initial configuration.
1

Clone the repository

Clone NibrasShell using a shallow clone to keep download size small:
git clone --depth 1 https://github.com/AhmedSaadi0/NibrasShell.git
2

Navigate to the installer directory

Move into the nibras_installer directory, which contains main.py:
cd NibrasShell/nibras_installer
3

Run the installer

Launch the interactive installer script:
python main.py
The script will ask you to choose a language (English, Arabic, or Czech), then present a menu with the following options:
  1. Install Dependencies — Installs all required system packages for your distribution
  2. Install NibrasShell — Copies config files, extracts themes, installs fonts, and creates ~/.nibrasshell.json
  3. Update Quickshell — Pulls the latest changes and re-copies the Quickshell config files
  4. Uninstall NibrasShell — Removes the shell and optionally restores a backup
  5. Create/Edit User Config — Re-runs the configuration wizard to regenerate ~/.nibrasshell.json
Run options 1 and then 2 on a fresh install.
Reboot your system after installation completes. Some components — including font changes and Plasma color integration — require a full restart to take effect.

​
Distro-specific notes

The installer detects your distribution automatically and uses the appropriate package manager. All three supported distributions use the same script — nibras_installer/main.py.
The installer uses yay to install packages from both the official repositories and the AUR. Make sure yay is installed before running the script.Key packages installed include: quickshell, hyprland, brightnessctl, konsole, dolphin, playerctl, polkit-kde-agent, kde-material-you-colors, plasma5support, fish, python, python313, and several others.Optional packages (installed when you choose Install All Dependencies) include: strawberry, easyeffects, blueman, telegram-desktop, discord, kvantum, and firefox.
# Ensure yay is available before running
which yay

​
What the installer does

When you run option 2 (Install NibrasShell), the script performs these steps automatically:
  1. Backs up your existing ~/.config/hypr, ~/.config/quickshell, and ~/.config/easyeffects directories to ~/.config/nibrasshell_backups/
  2. Copies Hyprland config files to ~/.config/hypr
  3. Copies Quickshell config files to ~/.config/quickshell
  4. Copies EasyEffects presets to ~/.config/easyeffects
  5. Copies the Fish shell config to ~/.config/fish/config.fish
  6. Extracts GTK themes to ~/.themes, icon packs to ~/.local/share/icons, and Kvantum themes to ~/.config/Kvantum
  7. Installs custom fonts (JF Flat, FantasqueSansM Nerd Font) to ~/.fonts
  8. Applies Plasma font settings via kwriteconfig6
  9. Runs the configuration wizard to create ~/.nibrasshell.json

​
Manual installation

If you are on a distribution not supported by the installer, you can set up NibrasShell manually.
1

Install dependencies

Install the following packages using your distribution’s package manager:
  • hyprland
  • quickshell
  • playerctl
  • polkit-kde-agent (or equivalent)
  • brightnessctl
  • wl-clipboard
  • cliphist
  • fish (shell)
  • python3 (3.13 recommended)
  • jq
  • sysstat
  • gammastep
  • konsole and dolphin (KDE terminal and file manager)
2

Clone and copy config files

git clone --depth 1 https://github.com/AhmedSaadi0/NibrasShell.git
cd NibrasShell
Copy the configuration directories to their destinations:
cp -r config/quickshell ~/.config/quickshell
cp -r config/hypr ~/.config/hypr
cp -r config/easyeffects ~/.config/easyeffects
cp config/config.fish ~/.config/fish/config.fish
3

Install themes and fonts

Extract GTK themes, icon packs, and install fonts:
mkdir -p ~/.themes ~/.local/share/icons ~/.fonts
# Extract archives from config/gtk-themes to ~/.themes
# Extract archives from config/icons to ~/.local/share/icons
# Copy fonts from config/.fonts to ~/.fonts
4

Create the user config file

Run the alternative installer script from the repository root to generate ~/.nibrasshell.json:
python install.py
Then select option 5 (Create/Edit User Config) from the menu.
After a manual install, you can use install.py from the repository root as an alternative to nibras_installer/main.py. Both scripts share the same menu structure and configuration wizard.

Build docs developers (and LLMs) love

Get started for freeTalk to us