<br/>

HyprFlux is an Arch Linux desktop operating system built around Hyprland - live ISO, installer, boot experience, login flow, theming, tooling, and a maintained desktop environment in one project.

<br/>

Quick Install • Screenshots • Features • Project Scope • Documentation • Contributing

</div>

Overview

HyprFlux is a complete Arch Linux desktop operating system project. It spans a branded live ISO, a text-based installer, automated system provisioning, curated packages, GTK theming, boot theming, login theming, wallpapers, developer tooling, and maintained desktop defaults.

Today, HyprFlux covers the full desktop stack:

the live ISO layer: a custom archiso-based image with HyprFlux branding, boot assets, and TUI installation flow
the desktop environment layer: Hyprland, Waybar, Rofi, Kitty, Zsh, Tmux, Neovim, scripts, keybinds, and workflow customization

The goal is simple: start from a fresh Arch installation and end up with a polished, consistent, production-ready Hyprland system without piecing everything together manually.

Project Scope

HyprFlux is designed as a complete operating system experience on top of Arch Linux, including:

a branded live ISO built on archiso
a custom TUI installer with automatic and manual partitioning flows
a reproducible install flow
a branded boot pipeline from GRUB to Plymouth to SDDM
a maintained Hyprland desktop environment
curated applications and developer tools
opinionated defaults with room for customization

The result is a cohesive operating-system-level experience that carries the same identity from power-on to login to daily use.

HyprFlux ISO

HyprFlux now includes a dedicated live ISO project as part of the wider platform direction.

The ISO is built on top of archiso and is designed to boot directly into a branded text-based installer that prepares a full HyprFlux system from a fresh machine.

Current ISO capabilities include:

x86_64 Arch Linux live image built with archiso
both UEFI and legacy BIOS boot support
a centered HyprFlux TUI installer launched automatically on tty1
automatic and manual partitioning modes
online installation flow with target-system provisioning
QEMU test tooling and CI-based ISO builds

In this repository, the ISO work currently lives under references/Hyprflux-ISO/ as a companion project reference while the main HyprFlux repository continues to own the desktop stack, assets, modules, and platform layer.

Screenshots

Desktop Overview

| Screenshot 0 | Screenshot 1 | | ------------------------------ | ------------------------------ | | Screenshot 2 | Screenshot 3 | | Screenshot 4 | Screenshot 5 | | Screenshot 6 | Screenshot 7 | | Screenshot 8 | Screenshot 9 |

</div>

Features

Platform Features

Custom Arch ISO: branded archiso image for installing HyprFlux from scratch
TUI installer: guided installation flow with live progress output
Automated install flow: modular setup with sane defaults and minimal manual work
Custom boot experience: branded GRUB, Plymouth, and SDDM integration
System theming: GTK, icons, cursors, wallpapers, and desktop-wide visual consistency
Hardware-aware setup: monitor configuration, cursor setup, theme wiring, and post-install scripts

Desktop Features

Hyprland with maintained configs and workflow-oriented defaults
Waybar with curated layouts and custom modules
Rofi for launching, switching, searching, and custom menus
SDDM with a HyprFlux-branded login theme

Developer Features

Neovim with a separate maintained config
Tmux and Zsh preconfigured for daily work
AI tooling support via AUR packages such as Claude Code, OpenAI Codex, Gemini CLI, and OpenCode
Web apps and utilities pre-integrated for modern workflows

Design Direction

HyprFlux identity: custom logos, boot branding, and consistent naming across the project
Deep, modern aesthetic: purple-led accent system, dark UI, and cohesive defaults
Practical customization: easy to swap wallpapers, layouts, profiles, themes, and scripts

Requirements

System Requirements

Base: Arch Linux
Architecture: x86_64
Memory: 4 GB minimum, 8 GB+ recommended
Storage: 10 GB minimum free space
Network: active internet connection for package installation

Recommended Starting Point

fresh Arch Linux installation
working internet connection
user account with sudo privileges
basic tools available: curl, git, sudo

Quick Installation

One-Line Install

sh <(curl -fsSL https://hyprflux.dev/install)

Installation Paths

HyprFlux currently supports two platform entry points:

direct install script for users starting from an existing Arch Linux install
HyprFlux ISO workflow for a full live-image-based installation path

What the installer does

installs required packages and desktop components
applies HyprFlux desktop configuration and user environment
configures themes, cursors, wallpapers, and startup behavior
sets up branded boot and login pieces where enabled
prepares a usable Hyprland desktop without manual post-install patching

Important HyprFlux changes system and user configuration. Use it on a fresh Arch setup or make backups before applying it to an existing environment.

Post-Installation

After installation completes:

reboot the machine if the installer requests it
log in through SDDM
let the first-boot steps finish
start customizing from the shipped configs and scripts

Useful locations:

Configs: ~/.config/
Themes: ~/.themes/
Icons and cursors: ~/.icons/
Wallpapers: ~/Pictures/wallpapers/
Backup: ~/dotfiles_backup/

Repository Layout

HyprFlux/
├── config/          # Project configuration files
├── dotsSetup.sh     # Main modular platform setup entrypoint
├── install.sh       # Primary install entrypoint
├── lib/             # Shared install helpers
├── modules/         # Modular install and setup steps
├── review/          # Screenshots and branding assets for the repo
├── references/      # Companion and upstream reference repositories, including ISO work
├── scripts/         # Installer helper scripts and automation patches
├── utilities/       # Themes, archives, logos, cursors, boot assets
└── .config/         # Maintained HyprFlux desktop environment files

Core Components

install.sh - top-level install entrypoint
dotsSetup.sh - orchestrates the modular setup flow
modules/ - feature-specific setup units such as GTK, SDDM, Plymouth, cursors, AI tools, and monitors
references/Hyprflux-ISO/ - companion ISO project reference built on archiso
.config/hypr/ - Hyprland configs, scripts, monitor profiles, and user overrides
.config/waybar/ - layouts, modules, and styling
.config/rofi/ - launcher and menu themes
.themes/HyprFlux-Compact/ - HyprFlux GTK theme
utilities/ - bundled assets used during installation

Documentation

Website: https://hyprflux.dev
Installation docs: https://hyprflux.dev/general/installation
Issues: https://github.com/ahmad9059/HyprFlux/issues

Contributing

Contributions are welcome.

You can help by:

reporting bugs with logs, screenshots, and reproduction steps
proposing platform improvements or desktop workflow ideas
improving installer reliability across more hardware setups
refining themes, layouts, branding, or documentation
sending pull requests for focused, well-tested changes

If you are making a larger change, open an issue first so the direction stays aligned with the project.

License

This project is licensed under the MIT License. See LICENSE.

Acknowledgments

JaKooLit - for the original foundation that HyprFlux grew from
Hyprland community - for the compositor and surrounding ecosystem
Arch Linux - for the base system that makes this possible
Open source maintainers - for the tools, themes, packages, and workflows HyprFlux builds on

Project Stats

GitHub repo size ![GitHub last

HyprFlux

Install / Use

README