Skip to content

FAQ

Jump to bottom
Trevin Tindall edited this page Aug 21, 2026 · 6 revisions

Frequently Asked Questions

General

What is Noctis-Hypr?

Noctis-Hypr is a modern, declarative Hyprland dotfiles collection built for three distinct identities:

  • Developer environment
  • Gaming rig
  • AI-assisted workflow

It provides a minimalist foundation that can be customized and extended through profiles and layers without losing its core design principles.

Why use Noctis-Hypr?

Noctis-Hypr was designed to keep moving - unlike many rice setups that are snapshots of configurations you copy over, Noctis is built with:

  • Declarative, not hardcoded - Package sets live as data (TOML files), not as bash arrays
  • Composable, not monolithic - Combine base profiles with optional layers without conflicts
  • Safe to run twice - Every install is snapshotted before changes
  • Honest about what it will do - --dry-run shows full install plan before touching anything
  • Reversible - Easy uninstallation that restores your previous setup

Is Noctis-Hypr only for Arch Linux?

Yes, Noctis-Hypr is designed specifically for Arch Linux and AUR packages. It hasn't been tested on other distributions and no distro branching is planned.

Installation

Can I run this on top of an existing Hyprland setup?

Yes. The installer snapshots your existing configs before touching anything (unless you pass --no-backup), and ./uninstall.sh restores the most recent snapshot if you want to back out.

What if I only want a subset of what full installs?

You can start from minimal and add only the layers you want, or edit profiles/custom_apps.lst before installing. Profiles and layers are just TOML - nothing stops you from forking one to fit exactly what you need.

How do I update Noctis-Hypr?

cd Noctis-Hypr
git pull
./install.sh

The installer detects your saved noctis.toml and re-resolves your profile/layers against any changes upstream, snapshotting your current configs first exactly as a fresh install would.

How do I uninstall?

./uninstall.sh

This restores your most recent backup. Pass --purge-packages if you also want it to remove everything your profile installed (behind its own separate confirmation).

Configuration

How does the profile/layer system work?

A profile is the base package set (minimal or full). A layer is an optional add-on merged on top (gaming, dev, ai).

You can combine any number of layers with a single profile. For example:

  • minimal + dev = lean coding box
  • full + gaming + dev = daily driver with gaming capabilities

What are custom apps?

Custom apps live in profiles/custom_apps.lst. These are automatically folded into the resolved package list during installation, so you don't need a separate prompt.

How do I customize keybindings?

Custom keybindings can be added by editing ~/.config/hypr/custom.lua. This file is never overwritten by the installer, so you can safely add your own bindings without them being lost during updates or re-runs.

Theming

Why isn't Firefox picking up my theme?

Firefox theming depends on the Pywalfox extension. Install this extension for Firefox theming to work.

How do I switch themes?

You can switch themes using the CLI:

noctis theme list          # List available themes
noctis theme set <name>    # Apply specific theme
noctis theme next          # Cycle to next theme
noctis theme prev          # Cycle to previous theme

Features

What are terminal games?

Noctis includes some fun terminal-based games accessible through the noctis play command:

  • Hangman: Classic word-guessing game
  • Snake: Control a snake to eat food and grow longer
  • Number Guessing: Try to guess a randomly generated number

Play them with:

noctis play hangman
noctis play snake
noctis play guess

Development

How can I contribute?

Contributions are welcome! The project is hosted on GitHub at T-Crypt/Noctis-Hypr. Feel free to submit issues, pull requests, or feature suggestions.

Are there any planned features?

The roadmap includes:

  • Gaming profile with performance-mode toggle and MangoHud integration
  • Enhanced dev environment with deeper terminal and editor tooling
  • Better theming architecture with directory-per-theme wallpaper sets
  • Settings CLI with noctis doctor drift check and GTK4 welcome window
  • Maintenance tooling for versioning, migrations, and CI

Performance

Is Noctis-Hypr resource-heavy?

Noctis-Hypr is designed to be lightweight while providing a rich experience. The default minimal profile uses fewer resources, while the full profile includes more features that may require additional system resources.

Why does the installer take so long?

The installation process can take time because:

  • It needs to resolve profiles and layers
  • It snapshots your current configuration before making changes
  • It installs packages from AUR (which can be time-consuming)
  • It generates themes from wallpapers

Compatibility

What Hyprland versions are supported?

Noctis-Hypr works with recent stable versions of Hyprland. The installer will work with the version that's available in your system's repositories.

Are there any known conflicts?

The system is designed to be compatible with standard Hyprland setups, but customizations in custom.lua might conflict with some default behavior. The installer preserves this file and won't overwrite it.

Clone this wiki locally