🖼 Preview

✨ Features

🧩 Stack

📦 Prerequisites

[!IMPORTANT]

The installer checks for these and warns about anything missing. It will not block installation unless core system utilities like cp or find are absent.

Tested On

| | | | :------------: | :------------------------------------------------ | | 🖥 OS | Arch Linux (latest) | | GPU | Intel / AMD / NVIDIA (all supported via Hyprland) | | 🪟 Display | Wayland (Hyprland) |

Core packages

yay -S hyprland waybar foot kitty zsh rofi mako       \
        hyprlock matugen-bin btop yazi fastfetch neovim starship          \
        cava cmus mpv nautilus zen-browser-bin aria2 advcpmv

Supporting packages

Fonts

The .fonts/ directory is bundled and installed automatically. To install manually:

yay -S ttf-jetbrains-mono-nerd ttf-font-awesome nerd-fonts-symbols-only
fc-cache -f

⚡ Installation

[!CAUTION]

Run --dry-run first on an existing setup. The installer backs up every file it will overwrite, but you should always confirm what it touches before committing.

Quick start

git clone https://github.com/Cybersnake223/Hypr
cd Hypr
chmod +x install.sh
./install.sh --dry-run   # preview first
./install.sh             # install when ready

What happens during install

[1] ✅  Verify core system utilities
[2] 🔍  Check Hyprland ecosystem packages
[3] 💾  Backup all files that will be overwritten
[4] 📁  Copy selected modules into $HOME
[5] 🔑  chmod +x all scripts in ~/.local/bin/scripts
[6] 🔤  Rebuild font cache via fc-cache -f
[7] 🛤  Detect shell and optionally patch PATH
[8] 📋  Print install summary with log path

Backups land here:

~/.local/share/hypr-dotfiles-backups/<YYYYMMDD-HHMMSS>/

Each backup contains a .manifest of every installed path — used by --uninstall to restore precisely.

Manual install (no script)

The installer is just a Bash script — review it, then replicate manually:

for dir in .config .icons .themes .fonts; do
  [ -d "$dir" ] && cp -r "$dir" "$HOME/"
done
[ -d .local/bin/scripts ] && cp -r .local/bin/scripts "$HOME/.local/bin/"
for f in .Xresources .gtkrc-2.0; do
  [ -f "$f" ] && cp "$f" "$HOME/"
done
find "$HOME/.local/bin/scripts" -type f -exec chmod +x {} +
fc-cache -f
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

📂 File Layout

$HOME
├── .config/
│   ├── hypr/             ← Hyprland compositor
│   ├── waybar/           ← Status bar
│   ├── rofi/             ← App launcher
│   ├── nvim/             ← Neovim
│   ├── zsh/              ← Zsh (uses $ZDOTDIR)
│   ├── kitty/            ← Kitty terminal
│   ├── foot/             ← Foot terminal
│   ├── mako/             ← Notifications
│   ├── yazi/             ← TUI file manager
│   ├── mpv/              ← Media player
│   ├── btop/             ← System monitor
│   ├── matugen/          ← Color templates
│   ├── fastfetch/        ← System info
│   ├── cava/             ← Audio visualizer
│   └── ...
├── .local/bin/scripts/   ← 50+ custom shell scripts
├── .fonts/               ← Bundled fonts
├── .icons/               ← Icon theme
├── .themes/              ← GTK/Qt themes
├── .Xresources
└── .gtkrc-2.0
/etc/ (system-level — not installed, apply manually): ├── auto-cpufreq.conf    ← CPU governor tuning ├── pacman.conf          ← Pacman parallel downloads + eye candy └── pacman.d/

🚩 Installer Flags

# First-timer recommended flow
./install.sh --dry-run
Standard install
./install.sh
Non-interactive (CI / scripted)
./install.sh --yes --skip-deps
Pick only what you want
./install.sh --select
Undo the last install
./install.sh --uninstall
See all saved backups
./install.sh --list-backups

--select module picker

[✓]  1  .config       Application configs (hypr, waybar, rofi, nvim, zsh…)
[✓]  2  scripts       Custom scripts → ~/.local/bin/scripts
[ ]  3  .icons        Icon theme
[✓]  4  .themes       GTK/Qt themes
[✓]  5  .fonts        Custom fonts (triggers fc-cache rebuild)
[✓]  6  dotfiles      Root dotfiles (.Xresources, .gtkrc-2.0)

Toggle a number, press Enter to confirm.

Shell-aware PATH patching

| Shell | Line added | File patched | | ------------ | --------------------------------------- | -------------------------------------- | | zsh | path=(~/.local/bin $path) | ~/.zshrc | | bash | export PATH="$HOME/.local/bin:$PATH" | ~/.bashrc | | fish | fishaddpath $HOME/.local/bin | ~/.config/fish/conf.d/hypr_path.fish | | ksh / mksh | export PATH="$HOME/.local/bin:$PATH" | ~/.kshrc | | Other | export PATH="$HOME/.local/bin:$PATH" | ~/.profile |

⌨️ Keybinds

[!NOTE]

ALT is the primary modifier across the entire setup.

🎨 Theming

This setup uses Matugen — a Material You color extraction engine. Change your wallpaper, run Matugen, and Waybar, Rofi, Mako, Hyprlock, GTK apps, and the terminal all recolor automatically.

# Set wallpaper and regenerate palette
aww set /path/to/wallpaper.jpg
matugen image /path/to/wallpaper.jpg

# Force a refresh from the cached wallpaper
matugen image ~/.config/hypr/wallpaper/current.jpeg

[!NOTE]

Matugen templates live in .config/matugen/. Edit them to control exactly how color tokens map to each app's config format.

🌐 Zen Browser

Custom styling for Zen Browser is included under .zen/chrome/ to match the Viper aesthetic.

| File | Purpose | | -------------------------------- | ------------------------------------------ | | .zen/chrome/userChrome.css | Browser chrome — sidebar, tab bar, toolbar | | .zen/chrome/userContent.css | Internal pages — new tab, about: pages | | .zen/chrome/zen-logo-mocha.svg | Custom logo asset |

[!IMPORTANT]

The installer does not copy .zen/ automatically. Apply it manually:

cp -r .zen/chrome "$HOME/.zen/chrome"

Then enable custom CSS in about:config:

toolkit.legacyUserProfileCustomizations.stylesheets = true

Restart Zen. If your profile is not at ~/.zen/ (e.g. Flatpak installs use ~/.var/app/), find the correct path via about:support → Profile Directory.

🔄 Updating

git pull
./install.sh --dry-run   # preview what changed
./install.sh             # apply

Each run creates a fresh backup. To roll back after an update:

./install.sh --uninstall      # restore most recent backup
./install.sh --list-backups   # or inspect all available backups

🔧 Troubleshooting

./install.sh --dry-run
which hyprland waybar rofi mako hyprlock matugen kitty foot zsh

# Zsh
echo 'path=(~/.local/bin $path)' >> ~/.zshrc
source ~/.zshrc
Bash / others
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

cp /path/to/Hypr/.gtkrc-2.0 ~/.gtkrc-2.0

matugen image /path/to/your/wallpaper

yay -S ttf-font-awesome nerd-fonts-symbols-only
fc-cache -f

# Show the last 50 lines of the most recent install log
tail -50 /tmp/hypr-install-*.log 2>/dev/null

🔐 Security

Do not open a public GitHub issue for vulnerabilities. See SECURITY.md for responsible disclosure.

🤝 Contributing

PRs are welcome for fixes, improvements, and documentation updates. Include screenshots when UI is affected.

💬 Getting Help

Need help or have questions? Start a discussion:

• GitHub Discussions — ask questions, share setups, get help

📄 License

MIT — see LICENSE for details.