You log into Fedora after a fresh install
The display manager shows GNOME, but you want a dynamic tiling workspace. You install Hyprland, log out, select it from the session menu, and press Enter. The screen goes black. The cursor disappears. You are stuck at a blank display with no way to switch to a TTY. This happens because Hyprland is a compositor, not a desktop environment. It does not start a panel, a file manager, or a lock screen by default. It waits for a configuration file that tells it how to draw windows and what programs to launch. Without that file, it starts, renders nothing, and drops you into a silent session.
What's actually happening
Hyprland operates at the Wayland protocol level. It talks directly to your GPU driver and the kernel input subsystem. GNOME or KDE wrap that compositor in a full desktop environment. They provide session management, default applications, theme engines, and automatic service startup. Hyprland provides only the window manager and the rendering pipeline. You are responsible for the rest.
Think of it like buying a house with only the foundation and walls. The plumbing, electricity, and furniture are not included. You must wire them yourself. The configuration file is your blueprint. It defines window rules, animations, keybindings, and the list of programs that should run when the session starts. If the blueprint is missing or contains a syntax error, Hyprland refuses to draw the workspace. It does not fall back to X11. It does not guess. It stops.
Fedora ships with a strict separation between system packages and user configuration. Files in /usr/lib/ are managed by dnf and will be overwritten on updates. Your Hyprland configuration lives in ~/.config/hypr/. This is the standard XDG base directory for user-specific application settings. Edits here survive package upgrades and system reboots. The compositor reads this path automatically on startup.
When you select Hyprland from the display manager, the session manager hands over the Wayland socket and your user credentials. Hyprland opens the socket, initializes the GPU context, and scans ~/.config/hypr/hyprland.conf. It parses the file line by line. Valid blocks are loaded into memory. Invalid blocks are skipped. The compositor then spawns the processes listed in [exec-once], draws the first workspace, and waits for input. If the config file is empty or missing, the compositor initializes the GPU context, finds no startup commands, and leaves you staring at a black screen.
Check the session logs before guessing. Run journalctl -xeu hyprland to see exactly where the startup sequence failed. Read the actual error before editing files.
The fix or how-to
Start by installing the core compositor and the essential utilities that make a bare Wayland session usable. Hyprland itself does not include a status bar, an application launcher, a terminal emulator, or a screen locker. You must install those separately.
Here is how to pull the base packages and the recommended ecosystem tools from the Fedora repositories.
sudo dnf install hyprland hyprlock hypridle hyprpaper waybar wofi kitty -y
# hyprland is the compositor. hyprlock handles the screen locker.
# hypridle manages DPMS and screen blanking. hyprpaper sets wallpapers.
# waybar provides the status panel. wofi is the application launcher.
# kitty is a GPU-accelerated terminal that works well with Wayland.
Create the configuration directory and a minimal startup file. Hyprland uses a custom configuration format that resembles INI files but supports arrays, conditional blocks, and dynamic variables. The syntax is strict. A missing bracket or a typo in a keyword will cause the compositor to ignore the entire block.
Here is how to generate a functional baseline configuration that prevents the black screen issue.
mkdir -p ~/.config/hypr
# Create the directory structure. Hyprland expects config files here.
# The -p flag prevents errors if the directory already exists.
cat > ~/.config/hypr/hyprland.conf << 'EOF'
# General compositor settings
[general]
gaps_in = 5
gaps_out = 10
border_size = 2
# gaps_in controls space between windows. gaps_out controls space at screen edges.
# border_size sets the thickness of the active window frame.
# Window decoration and rendering
[decoration]
blur = yes
blur_size = 5
blur_ignore_opacity = true
# Enables background blur for floating windows and menus.
# blur_ignore_opacity prevents transparent windows from breaking the effect.
# Input and cursor behavior
[input]
kb_layout = us
follow_mouse = 1
# Sets the default keyboard layout. follow_mouse = 1 makes the active window
# switch when the cursor enters it, which matches desktop environment behavior.
# Startup programs
[exec-once]
exec = hyprpaper
exec = waybar
exec = hypridle
exec = hyprlock
# exec-once runs these commands exactly once when the session starts.
# hyprpaper loads the background. waybar draws the panel.
# hypridle and hyprlock handle power management and locking.
EOF
Add keybindings so you can actually control the workspace. Hyprland does not ship with a default keymap. You must define how to launch applications, switch workspaces, and move windows.
Here is how to wire up the essential shortcuts that make tiling workflows functional.
cat >> ~/.config/hypr/hyprland.conf << 'EOF'
# Keybindings
bind = SUPER, RETURN, exec, kitty
bind = SUPER, Q, killactive,
bind = SUPER, D, exec, wofi --show drun
bind = SUPER, M, fullscreen,
bind = SUPER, V, togglefloating,
bind = SUPER, left, movefocus, l
bind = SUPER, right, movefocus, r
bind = SUPER, up, movefocus, u
bind = SUPER, down, movefocus, d
# SUPER is the Windows key. RETURN launches the terminal.
# Q kills the active window. D opens the application launcher.
# M toggles fullscreen. V toggles floating mode.
# Arrow keys shift focus between tiled windows.
EOF
Log out of your current GNOME or KDE session. The display manager will show a session selector, usually located in the bottom left or top right corner. Select Hyprland from the dropdown. Enter your password and press Enter. The compositor will read ~/.config/hypr/hyprland.conf, launch the four background services, and render your first workspace.
Reboot before you debug. Half the time the symptom is gone after a clean session handoff.
Verify it worked
Open a terminal by pressing Super + Enter. This keybinding is hardcoded into Hyprland and cannot be disabled. Run the following command to confirm the compositor is running and reading your configuration correctly.
hyprctl monitors
# Queries the active monitor configuration.
# Returns resolution, refresh rate, and scale factor.
# If this command hangs or returns nothing, the compositor crashed.
Check the startup logs to ensure no configuration blocks were skipped. Hyprland writes detailed parsing logs to a cache file. The log shows exactly which lines were accepted and which triggered syntax warnings.
cat ~/.cache/hypr/hyprland.log | grep -i "error\|warning\|parsed"
# Filters the log for parsing results.
# Look for "Successfully parsed" next to your config blocks.
# Any "Failed to parse" line points to a syntax mistake.
Run hyprctl clients to verify that your terminal, status bar, and wallpaper daemon are registered as active Wayland surfaces. If the list is empty, the [exec-once] block failed to launch. Check the terminal output for permission errors or missing binaries.
Use hyprctl reload after every configuration change. The compositor applies the new rules instantly without requiring a logout. Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and what the error looks like
Configuration syntax is the most frequent cause of startup failures. Hyprland does not validate the entire file before starting. It parses line by line. A missing closing bracket on line 15 will cause every line after it to be ignored. The compositor will start, but your keybindings and startup programs will be missing.
You will see this warning in the log when a block is malformed:
[WARNING] Failed to parse config line: "exec = waybar"
[ERROR] Missing closing bracket for section [exec-once]
The error does not crash the session. It silently drops the malformed section. You get a working window manager with no panel, no wallpaper, and no lock screen. Always check the log after editing the configuration.
Another common issue involves Wayland permissions. Hyprland requires access to the session bus and the input method framework. If you see a black screen with a visible cursor, the compositor likely failed to initialize the rendering pipeline. This usually happens when the GPU driver is missing or when hyprland is run inside an X11 session without proper nesting support. Fedora uses mesa drivers by default. Ensure mesa-dri-drivers and libva-mesa-driver are installed. Missing VA-API packages break hardware acceleration and cause the compositor to fall back to software rendering, which often fails on modern hardware.
Screen sharing and recording also require PipeWire configuration. Hyprland does not include a portal implementation. Fedora ships xdg-desktop-portal and xdg-desktop-portal-wlr. Without the WLR portal, applications like Zoom, Teams, and OBS cannot capture the Wayland surface. You will get a black screen in the video call or a "no source available" error in OBS. Install the portal package and restart the session. The compositor registers with the portal automatically on startup.
The difference between exec and exec-once also trips up new users. exec runs a command every time you switch workspaces or trigger a reload. exec-once runs it exactly one time when the session starts. Use exec-once for daemons like waybar, hyprpaper, and hypridle. Use exec for commands you want to trigger manually through keybindings. Putting a daemon in exec will spawn duplicate processes on every reload.
Run journalctl -xe first. Read the actual error before guessing.
When to use this vs alternatives
Use Hyprland when you want a highly customizable, animation-heavy tiling compositor that runs on Wayland. Use Sway when you need a stable, i3-compatible window manager with a mature plugin ecosystem and predictable behavior. Use GNOME or KDE when you want a complete desktop environment with built-in settings panels, file managers, and automatic service management. Use X11 tiling window managers like i3 or bspwm when you are running legacy applications that require X11 forwarding or when you need to run multiple independent X sessions. Stay on the default Fedora Workstation if you only deviate from the defaults occasionally and prefer system stability over window management control.