You installed Sway and the screen went black
You spent a week fighting the mouse in GNOME and decided you want a keyboard-driven workflow. You run the install command, log out, and select Sway from the login screen. The display goes completely dark. Or it drops you into a tiny windowed Sway instance floating inside the GNOME desktop. You are left guessing why the compositor refuses to claim the display, why your keybindings do nothing, and why your external monitor shows nothing.
What is actually happening under the hood
Sway is not a desktop environment. It is a Wayland compositor that replaces i3. Wayland compositors do not share a single display server like X11 does. Each compositor claims direct control over the GPU, input devices, and screen output. Fedora ships with GDM as the default display manager. GDM knows how to launch GNOME and KDE. It does not automatically know how to hand over the seat to Sway unless you tell it exactly which session type to request.
The configuration file is also not optional. Sway will fall back to hardcoded defaults that rarely match modern laptop screens or external monitors. You need to declare your keybindings, output scaling, and application launcher explicitly. The compositor reads the file once at startup. If the syntax is wrong, Sway aborts silently and drops you back to the login prompt.
Wayland also changes how applications request screen real estate. There is no global DISPLAY variable. Each client connects to the compositor over a Unix socket. The compositor decides where windows go, how they scale, and whether they get input focus. You configure that behavior in a single text file. Trust the package manager for the binaries. Trust the config file for the behavior.
Install the compositor and supporting tools
You need the core compositor, a terminal emulator, an application launcher, a screen locker, and an idle handler. Fedora packages these separately because Sway follows the Unix philosophy of small, composable tools.
Here is how to pull the required packages from the default repositories.
sudo dnf install sway wofi swaylock swayidle wlr-randr
# wofi provides a fast, keyboard-friendly application launcher
# swaylock handles screen locking with Wayland-native authentication
# swayidle manages DPMS and triggers swaylock after inactivity
# wlr-randr is a legacy helper for output management, kept for compatibility
Fedora keeps the core compositor lightweight. You will notice that swaybg is no longer a separate package. The background rendering logic moved into the main Sway binary in version 1.8. Installing it separately will pull in deprecated dependencies. Stick to the core set above.
Run dnf upgrade --refresh after installing. The refresh flag forces the package manager to fetch the latest metadata before resolving dependencies. This prevents partial transactions when the repository mirrors are slightly out of sync.
Write a functional configuration file
Sway expects its configuration at ~/.config/sway/config. The directory must exist before the compositor starts. The file uses a simple key-value syntax. Comments start with #. Indentation does not matter, but consistency makes debugging easier.
Here is a minimal configuration that covers keybindings, output scaling, and the application launcher.
# Set the modifier key to Super (Windows key)
set $mod Mod4
# Bind Super+D to launch the wofi application menu
bindsym $mod+d exec wofi --show drun
# Bind Super+Q to kill the focused window
bindsym $mod+q kill
# Set default output scaling for HiDPI laptops
output * scale 2
# Set a terminal emulator as the default for Super+Enter
bindsym $mod+Return exec alacritty
# Define the keybinding to reload the configuration without restarting
bindsym $mod+Shift+c reload
The set $mod Mod4 line creates a variable so you can change your modifier key in one place. The bindsym directives map keyboard combinations to actions. The output * scale 2 directive tells the compositor to apply a 2x scaling factor to all connected displays. Adjust the number to match your panel density. The reload binding is essential. You will edit this file repeatedly. Restarting the entire session to test a single keybinding wastes time.
Config files in ~/.config/ are user-modified. Files in /usr/share/sway/ ship with the package. Never edit the system defaults. Your local file overrides them completely. If you accidentally delete your config, Sway falls back to the system default and ignores your keybindings.
Tell the display manager to launch Wayland
GDM looks for .desktop files in /usr/share/wayland-sessions/ to populate the session selector. The Sway package installs sway.desktop automatically. You usually do not need to touch it. You only need to configure GDM to recognize the session type if you are using a minimal install or a custom display manager.
Here is how to verify that the session file exists and points to the correct executable.
cat /usr/share/wayland-sessions/sway.desktop
# Check that Exec points to /usr/bin/sway
# Check that Type is Application
# Check that DesktopNames contains sway
If you are logging in via GDM, click the gear icon in the bottom-left corner of the login screen and select Sway. The display manager will set XDG_SESSION_TYPE=wayland automatically. You do not need to export it in ~/.bashrc. Exporting it manually can break X11 fallback applications and confuse desktop environment integrations.
If you prefer to start Sway from a TTY without a display manager, use the startsway wrapper. It handles XDG variables and session cleanup.
# Switch to a virtual console with Ctrl+Alt+F3
# Log in with your username and password
startsway
# startsway sets XDG_SESSION_TYPE=wayland and starts the compositor
# It also ensures swaymsg can communicate with the running instance
Log out and select the Sway session from the login screen. If you are using a TTY, run startsway and press Enter. The compositor will claim the display immediately.
Verify the session is running correctly
Sway does not show a system tray or a status bar by default. You need to query the compositor directly to confirm it is active and managing your outputs.
Here is how to check the running version and verify output detection.
swaymsg -t get_version
# Returns the exact Sway version and build date
# Confirms the compositor is accepting IPC commands
swaymsg -t get_outputs
# Lists all connected displays, their resolution, and scaling factor
# Returns an empty array if the compositor failed to claim the GPU
Run echo $XDG_SESSION_TYPE in your terminal. The output must be wayland. If it returns x11, GDM launched the wrong session or your display manager configuration is overriding the selection. Check the session selector again.
Run swaymsg -t get_inputs to verify that your keyboard and touchpad are registered. Missing input devices usually indicate a udev rule conflict or a missing libinput package. Install libinput if the input list is empty.
Check the compositor logs with journalctl -xeu sway. The x flag adds explanatory context. The e flag jumps to the end. Read the actual error before guessing.
Common pitfalls and what the error looks like
A black screen after selecting Sway usually means the compositor failed to bind to the GPU or the config file contains a syntax error. Sway prints the failure to the journal and drops you back to GDM.
The sway unit will refuse to start and print Error: Failed to initialize Wayland compositor: Device or resource busy. The conflict is intentional. Another compositor is already holding the DRM master lock. Log out of GNOME or KDE completely before launching Sway.
If you see wofi: command not found when pressing your launcher keybinding, the package did not install correctly or your PATH is missing /usr/bin. Run which wofi to confirm the binary location. Add the correct path to your bindsym directive if it lives in /usr/local/bin.
Output scaling often breaks on mixed-DPI setups. The output * scale 2 directive applies globally. If you connect a 1080p external monitor to a 4K laptop, the external display will look tiny. Replace the wildcard with explicit output names.
# Query the exact output name first
swaymsg -t get_outputs | grep name
# Apply scaling per-output instead of globally
output eDP-1 scale 2
output HDMI-A-1 scale 1
SELinux denials show up in journalctl -t setroubleshoot with a one-line summary. Read those before disabling SELinux. Sway runs with the sway_t domain. If you compile custom input methods or run unconfined X11 clients, the policy will block them. Use audit2allow to generate a custom module instead of switching to permissive mode.
Reboot before you debug. Half the time the symptom is gone after a clean DRM mode switch.
When to use Sway versus other desktop setups
Use Sway when you want a keyboard-driven, tiling workflow that runs natively on Wayland. Use GNOME when you need a polished, mouse-friendly desktop with built-in accessibility and hardware integration. Use KDE Plasma when you want deep customization options and a traditional window manager experience. Use Hyprland when you want animated, GPU-accelerated tiling with a steeper learning curve. Stay on the upstream Workstation if you only deviate from the defaults occasionally.