Flouda Vault

9 min read

Complete Hyprland Desktop Environment Setup Guide

This comprehensive guide walks you through setting up a complete Hyprland desktop environment on Arch Linux, from base installation to a fully configured, beautiful desktop that feels like home. This setup combines the power of Hyprland’s tiling window manager with carefully selected applications and themes for a productive and aesthetically pleasing experience.

What This Guide Covers

This guide provides everything needed to transform a minimal Arch Linux installation into a fully functional desktop environment featuring:

  • Hyprland Wayland Compositor: Modern tiling window manager with smooth animations
  • Complete Audio Stack: PipeWire configuration for professional audio handling
  • Terminal Environment: Zsh with Oh My Zsh, powerful utilities, and custom configurations
  • Development Setup: Neovim with full IDE capabilities and development tools
  • Visual Consistency: Coordinated themes, fonts, and color schemes throughout
  • Automation Scripts: One-command setup for major components

Quick Start with Automation

For those who want to jump straight to the results, use the automated setup script:

curl -fsSL https://vault.flouda.io/setup-desktop | bash

This script handles the entire process automatically. For those who want to understand each step or customize the setup, continue with the detailed instructions below.

Prerequisites and Base Installation

Arch Linux Installation

Start with a minimal Arch Linux installation using archinstall with the minimal profile. This provides a clean foundation without unnecessary packages that might conflict with the Hyprland setup.

Essential Build Tools

After the base installation, install essential tools for building packages from the AUR:

sudo pacman -Sy --noconfirm git wget base-devel

Add microcode updates for your processor (choose the appropriate one):

# For AMD processors
sudo pacman -S --noconfirm amd-ucode
 
# For Intel processors  
sudo pacman -S --noconfirm intel-ucode

AUR Helper Installation

Install yay for easy AUR package management:

git clone https://aur.archlinux.org/yay.git
cd yay
makepkg -si --noconfirm
cd .. && rm -rf yay

Hyprland Desktop Environment Setup

Core Hyprland Packages

Install the complete Hyprland ecosystem with supporting applications:

yay -Sy --noconfirm --needed \
  hyprland \
  hyprpaper \
  hyprlock \
  hyprcursor \
  xdg-desktop-portal-hyprland \
  xdg-desktop-portal-gtk \
  polkit \
  wofi \
  waybar \
  greetd \
  greetd-regreet \
  kitty \
  uwsm \
  papirus-icon-theme \
  swaync \
  xorg-xhost \
  polkit-gnome \
  nemo \
  nemo-fileroller \
  brightnessctl \
  playerctl

Audio System

Configure PipeWire for professional audio handling:

yay -Sy --noconfirm --needed \
  pipewire \
  pipewire-pulse \
  pipewire-alsa \
  wireplumber \
  pipewire-jack \
  pavucontrol

Fonts and Themes

Install comprehensive font collection and visual themes:

yay -Sy --noconfirm --needed \
  nwg-look \
  otf-font-awesome \
  ttf-font-awesome \
  ttf-nerd-fonts-symbols \
  ttf-fira-code \
  ttf-input \
  ttf-liberation \
  ttf-ubuntu-font-family \
  ttf-dejavu \
  noto-fonts \
  nerd-fonts \
  bettergruvbox-gtk-theme \
  papirus-folders \
  bibata-cursor-theme-bin

Utility Applications

Install essential desktop utilities:

yay -Sy --noconfirm --needed \
  wl-clipboard \
  eog \
  grim \
  slurp \
  hyprpicker \
  jq \
  gnome-text-editor \
  npm \
  nodejs \
  tesseract \
  tesseract-data-eng \
  wlogout \
  grimblast-git \
  zen-browser-bin \
  bemoji \
  wtype \
  obsidian \
  qutebrowser

Configuration and Dotfiles

Dotfiles Repository

Clone the complete configuration repository:

git clone https://gitlab.com/flouda/dotfiles
cd dotfiles

System Configuration Files

Install system-wide configuration files:

# Install display manager configuration
sudo cp greetd/* /etc/greetd/
 
# Install wallpaper
sudo mkdir -p /usr/share/backgrounds/
sudo cp wp.png /usr/share/backgrounds/
cp wp.png ~/

User Configuration Files

Deploy user-specific configuration files:

# Copy all hidden dotfiles to home directory
cp -r user-home/.* ~/

This includes configurations for:

  • Hyprland window manager settings
  • Waybar status bar configuration
  • Kitty terminal emulator setup
  • Application launchers and shortcuts
  • Custom key bindings and workspace rules

System Services Configuration

Display Manager

Enable the Greetd display manager for automatic login handling:

sudo systemctl enable --now greetd

GTK Theme Configuration

Configure system-wide GTK themes for visual consistency:

# Set GTK3 and GTK4 themes to BetterGruvbox
gsettings set org.gnome.desktop.interface gtk-theme BetterGruvbox
 
# Configure Nemo file manager to open terminal in current directory
gsettings set org.cinnamon.desktop.default-applications.terminal exec kitty

Terminal Environment Setup

Core Terminal Tools

Install essential terminal utilities:

sudo pacman -Sy --noconfirm zsh fzf ranger tmux zoxide

These tools provide:

  • Zsh: Advanced shell with powerful features
  • fzf: Fuzzy finder for files and command history
  • Ranger: Terminal-based file manager
  • Terminal Multiplexer: tmux for session management with custom keybindings
  • Zoxide: Smart directory jumping

Oh My Zsh Framework

Install the Oh My Zsh framework for enhanced shell experience:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Zsh Plugins

Install essential Zsh plugins for syntax highlighting and autosuggestions:

# Syntax highlighting plugin
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
 
# Autosuggestions plugin
git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

Zsh Configuration

If you’ve already placed dotfiles, restore the custom Zsh configuration:

cd ~
rm .zshrc
mv .zshrc.pre-oh-my-zsh .zshrc

Alternatively, download the configuration directly:

rm ~/.zshrc $ZSH_CUSTOM/aliases.zsh
wget https://gitlab.com/flouda/dotfiles/-/raw/main/user-home/.zshrc?ref_type=heads -O ~/.zshrc
wget https://gitlab.com/flouda/dotfiles/-/raw/main/user-home/aliases.zsh?ref_type=heads -O $ZSH_CUSTOM/aliases.zsh

Development Environment

Development Environment

For a complete development environment, install and configure Neovim with IDE capabilities. The automated Neovim setup utility provides comprehensive instructions for installing a modern development environment with language servers, debugging support, and advanced editing features.

Quick installation for development essentials:

sudo pacman -Sy --noconfirm neovim npm nodejs go ripgrep fzf base-devel
git clone --depth 1 https://gitlab.com/flouda/dotfiles && \
  mv dotfiles/user-home/.config/nvim ~/.config/ && \
  rm -rf dotfiles

Storage Requirements: The complete Neovim setup requires approximately 500MB of disk space due to language servers and plugins. You can minimize this by disabling Mason or customizing the plugin selection.

Automated Neovim Installation

For automated setup across different distributions, use the dedicated Neovim setup script:

curl -fsSL https://vault.flouda.io/scripts/setup-nvim | bash

This cross-platform script works on both Arch Linux and Ubuntu systems, automatically handling dependency installation, source compilation when needed, and deploying a complete IDE configuration with language servers and modern development features.

Key Features and Workflow

Window Management

Hyprland provides powerful tiling window management with:

  • Automatic Tiling: Windows automatically arrange in optimal layouts
  • Workspaces: Multiple virtual desktops for organization
  • Floating Windows: Support for traditional floating windows when needed
  • Custom Rules: Application-specific window behavior
  • Smooth Animations: Beautiful transitions and effects

Application Launching

  • Wofi: Application launcher with fuzzy search
  • Bemoji: Emoji picker with quick access
  • Waybar: Status bar with system information and workspace indicators

System Integration

  • Notifications: Desktop notifications via SwayNC
  • Audio Control: PulseAudio/PipeWire integration with media keys
  • Brightness Control: Laptop brightness control via function keys
  • Screenshot Tools: Grim and Slurp for screen capture
  • Color Picker: Hyprpicker for selecting colors from screen

File Management

  • Nemo: Full-featured file manager with archive support
  • Ranger: Terminal-based file manager with vim-style navigation for power users
  • Integration: Consistent file handling across applications

Customization and Theming

Theme Consistency

The setup uses the BetterGruvbox theme across all applications for visual consistency:

  • GTK Applications: Unified theme for all GUI applications
  • Terminal: Coordinated color scheme in terminal applications
  • Icons: Papirus icon theme with folder color customization
  • Cursors: Bibata cursor theme for modern appearance

Font Configuration

Comprehensive font setup includes:

  • Programming: Fira Code with ligatures for development
  • Interface: Ubuntu and Liberation fonts for UI elements
  • Icons: Font Awesome and Nerd Fonts for symbols
  • Multilingual: Noto Fonts for international character support

Troubleshooting and Tips

Common Issues

Audio Problems: If audio doesn’t work after installation, restart PipeWire services:

systemctl --user restart pipewire pipewire-pulse wireplumber

Display Issues: For multi-monitor setups, configure displays in the Hyprland configuration file at ~/.config/hypr/hyprland.conf.

Application Scaling: For HiDPI displays, adjust scaling in the Hyprland configuration or use the nwg-look tool for GTK applications.

Performance Optimization

  • GPU Acceleration: Ensure proper graphics drivers are installed for your GPU
  • Memory Usage: The complete setup uses approximately 1-2GB of RAM at idle
  • Startup Time: First boot may be slower as fonts and themes are cached

Backup and Recovery

Before major changes, backup your configuration:

tar -czf ~/dotfiles-backup-$(date +%Y%m%d).tar.gz ~/.config

References and Resources

Official Documentation

Source Repository

Questions Answered in This Document

Q: What is Hyprland and why should I use it? A: Hyprland is a modern Wayland compositor and tiling window manager that provides smooth animations, powerful customization options, and efficient workspace management. It’s ideal for users who want a productive, keyboard-driven desktop environment with beautiful visual effects.

Q: Can I use the automated setup script safely? A: Yes, the automated setup script is designed for fresh Arch Linux installations with minimal profiles. It installs all necessary packages and configurations automatically. However, review the script contents if you have an existing setup to avoid conflicts.

Q: How much disk space does the complete setup require? A: The base Hyprland setup requires approximately 2-3GB of disk space. With the complete Neovim development environment, expect around 3-4GB total. The Neovim configuration alone uses about 500MB for language servers and plugins.

Q: Is this setup suitable for laptops? A: Absolutely. The setup includes laptop-specific features like brightness controls, battery indicators in the status bar, power management integration, and touch gestures. It’s optimized for both desktop and laptop use.

Q: Can I customize the theme and appearance? A: Yes, the setup is highly customizable. You can modify themes in the dotfiles repository, change color schemes in individual application configs, or use tools like nwg-look for GTK theme management. The BetterGruvbox theme can be replaced with any GTK theme.

Q: What if I encounter issues during installation? A: Most issues are related to missing dependencies or conflicts with existing configurations. Ensure you’re starting with a clean minimal Arch installation, check that all packages installed successfully, and verify system services are running. The troubleshooting section covers common problems.

Q: Is this setup compatible with NVIDIA graphics cards? A: Yes, but NVIDIA users may need additional configuration for optimal Wayland support. Install appropriate NVIDIA drivers and enable DRM kernel mode setting. Some NVIDIA-specific Hyprland configurations may be required for best performance.

Q: Can I use parts of this setup without installing everything? A: Absolutely. Each major component (Hyprland, terminal setup, Neovim) can be installed independently. The modular approach allows you to pick and choose components that fit your needs without installing the complete environment.

Q: How does this compare to other desktop environments like GNOME or KDE? A: This Hyprland setup focuses on tiling window management, keyboard-driven workflows, and minimal resource usage compared to traditional desktop environments. It’s more customizable but requires more initial setup. Choose this if you prefer efficiency and customization over out-of-the-box functionality.

Graph View

Backlinks