Your keyboard is dead or your remote session won't type
Your laptop keyboard just stopped responding, or you are managing a headless server via a remote desktop client that doesn't pass key events correctly. You need an on-screen keyboard immediately. Fedora includes gnome-screen-keyboard by default, but it stays hidden until you enable it. The keyboard is part of the GNOME accessibility stack, not a standalone utility you install separately.
How the on-screen keyboard works
The on-screen keyboard is controlled by a single setting in the GNOME desktop configuration. When enabled, GNOME Shell launches the keyboard process and docks it to the screen. The keyboard listens for focus changes and injects input events into the active window.
On Wayland, which is the default session on Fedora, the keyboard operates as a client of the compositor. The compositor mediates all input events. This means the on-screen keyboard can only type into windows that the compositor allows, which is a security feature. Random applications cannot inject keystrokes into other applications without compositor permission. gnome-screen-keyboard has this permission built-in.
On X11, the keyboard uses X11 input protocols to inject events. This is less secure because any X11 client can theoretically inject keys, but it offers more flexibility for legacy tools. The configuration commands are identical for both display servers.
The keyboard does not require the Orca screen reader. Orca is a separate accessibility tool for visually impaired users who need audio feedback and braille support. Installing Orca adds unnecessary weight if you only need a visual keyboard. The core dependency is at-spi2-atk, which provides the accessibility bus. This package is installed by default on Fedora Workstation.
Run rpm -q at-spi2-atk to verify the accessibility infrastructure is present. If the package is missing, your system is in a non-standard state.
Enable the keyboard via gsettings
The standard way to enable the keyboard is through gsettings. This command writes to the dconf database, which GNOME Shell monitors in real time. The change takes effect immediately without a reboot.
gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true
# WHY: Writes the persistent configuration to the dconf database.
# GNOME Shell watches this key and launches the keyboard process automatically.
You can also control the layout mode. The keyboard can dock at the bottom of the screen or float as a window. Docking is better for permanent access. Floating is better for temporary use.
gsettings set org.gnome.desktop.a11y.applications screen-keyboard-layout dock
# WHY: Sets the keyboard to dock at the bottom of the screen.
# Use 'window' for a floating keyboard or 'dock' for persistent access.
If you need to test the binary directly without relying on the shell integration, launch it manually. This is useful for debugging.
gnome-screen-keyboard &
# WHY: Launches the keyboard in the background for immediate testing.
# This bypasses the shell integration, useful for verifying the binary works.
Run gsettings get org.gnome.desktop.a11y.applications screen-keyboard-enabled before you reboot. If the value is false, your fix didn't stick.
Verify the configuration
After enabling the keyboard, confirm the setting persisted and the process is running. The gsettings command reads back the value from the database. The pgrep command checks for the running process.
gsettings get org.gnome.desktop.a11y.applications screen-keyboard-enabled
# WHY: Confirms the setting is persisted. Output must be true.
# If the output is false, the previous set command failed or was overridden.
pgrep -a gnome-screen-keyboard
# WHY: Lists the running keyboard process with its PID and command line.
# If this returns nothing, the process failed to start or crashed.
Check the journal if the process is missing. The logs show why the application exited.
journalctl -xeu gnome-screen-keyboard
# WHY: Shows recent logs and explanatory text for the keyboard unit.
# Look for errors related to missing dependencies or display connection failures.
Read the actual error in the journal before guessing. Half the time the symptom is a missing library or a display environment variable issue.
Troubleshooting layout and input issues
The on-screen keyboard mirrors your system input sources. If the keyboard shows QWERTY but you need AZERTY, the issue is not the keyboard. The issue is the input source configuration. GNOME manages keyboard layouts centrally. The on-screen keyboard reflects the active layout.
Check the current input sources.
gsettings get org.gnome.desktop.input-sources sources
# WHY: Lists the active keyboard layouts. The on-screen keyboard mirrors these.
# Output is a tuple of layout codes, e.g., [('xkb', 'us'), ('xkb', 'fr')].
If the layout is wrong, update the input sources. This changes the layout for the entire session, including the on-screen keyboard.
gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('xkb', 'de')]"
# WHY: Sets the list of available keyboard layouts.
# The on-screen keyboard will switch keys to match the active layout.
Some GNOME Shell extensions can interfere with the keyboard. Extensions that modify the top bar or window management may hide the docked keyboard or block input events. List your active extensions.
gnome-extensions list
# WHY: Shows all installed extensions and their enabled status.
# Disable extensions one by one to isolate conflicts.
If you are using a remote desktop tool like VNC or RDP, the on-screen keyboard may not work correctly. Remote protocols often capture input at a lower level than the display server. The keyboard injects events into the local session, but the remote client might not forward them back. In this case, the keyboard works locally, but the remote session sees nothing. Use a remote desktop protocol that supports input injection, or configure the remote tool to allow local input passthrough.
Check SELinux denials if the process fails to start on a locked-down system. Standard Fedora installations allow gnome-screen-keyboard, but custom policies might block it.
sudo ausearch -m avc -ts recent | grep screen-keyboard
# WHY: Searches the audit log for SELinux access vector cache denials.
# A denial here means the security policy is blocking the process.
If you see denials, generate a local policy module. Do not disable SELinux. A botched security configuration can expose your system to privilege escalation. Generate a targeted allow rule instead.
Trust the package manager. Manual file edits drift, snapshots stay. If you modify binaries or libraries to force the keyboard to work, the next update will break your changes.
Systemd service for non-GNOME setups
If you are running a minimal desktop environment or a headless setup where GNOME Shell is not present, gsettings will not launch the keyboard. You need a systemd user service to manage the process. This approach works on any desktop that provides a display server.
Create a service file in your user configuration directory. This file defines how systemd should start and manage the keyboard.
[Unit]
Description=On-Screen Keyboard Service
After=graphical-session.target
# WHY: Ensures the display server is running before the keyboard starts.
# The keyboard cannot launch without a graphical session.
[Service]
Type=simple
ExecStart=/usr/bin/gnome-screen-keyboard
Restart=on-failure
# WHY: Restarts the process if it crashes, keeping the keyboard available.
# This is critical for headless systems where you cannot manually restart apps.
[Install]
WantedBy=default.target
# WHY: Starts the service when the user session begins.
# default.target pulls in the standard user session units.
Save the file as ~/.config/systemd/user/screen-keyboard.service. Reload the user manager and enable the service.
systemctl --user daemon-reload
# WHY: Tells systemd to scan for new or changed unit files.
# Without this, systemd ignores the new service file.
systemctl --user enable --now screen-keyboard.service
# WHY: Enables the service for future boots and starts it immediately.
# The --now flag combines enable and start in one command.
Check the service status to confirm it is active.
systemctl --user status screen-keyboard.service
# WHY: Shows the current state, recent logs, and resource usage.
# Look for 'active (running)' in the output.
Use a systemd user service when you are on a minimal desktop environment or need the keyboard to survive a shell crash. Use gsettings when you are running the default GNOME desktop and want the keyboard to integrate with the top bar and session lifecycle. Use the Accessibility GUI toggle when you are configuring a system for a user who prefers visual configuration over the terminal. Stay on the upstream gsettings method if you only deviate from the defaults occasionally.
Run journalctl --user -u screen-keyboard if the service fails. The user journal contains the startup errors.