KDE Plasma 6: Install, Configure and Troubleshoot

Install KDE Plasma 6

A distro edition built around Plasma gives the best result, because its defaults, display manager and apps are tested together. Adding Plasma to an existing desktop also works:

Log out, choose Plasma (Wayland) from the session menu on the login screen, and log in. Check the version with:

plasmashell --version
kinfo     # summary of Plasma, Frameworks, Qt, kernel and graphics

Wayland or X11 session

Plasma 6 defaults to Wayland, which gives you per-monitor fractional scaling, mixed refresh rates, HDR on supported hardware and better touchpad gestures. The X11 session is still maintained but some distributions no longer install it by default. Stay on Wayland unless a specific tool you need is X11-only; the trade-offs are covered in Wayland vs X11.

# which session am I in?
echo $XDG_SESSION_TYPE

NVIDIA users: Wayland works well with current drivers. Make sure kernel modesetting is enabled (it is by default with the open modules) and see NVIDIA black screen fix if the session fails to start.

Panels, widgets and the desktop

Right-click the panel or desktop and choose Enter Edit Mode (or Show Panel Configuration). From there:

• Panel: change position, height, alignment, visibility (always visible, auto-hide, dodge windows) and the floating style. Add a second panel with Add Panel.
• Widgets: Add Widgets opens the widget explorer; drag one onto the panel or desktop. Get New Widgets downloads community widgets from the KDE Store (review them; they are third-party code).
• Task Manager style: right-click the task manager → Show Alternatives to switch between icons-only and the classic labelled taskbar.
• Desktop: wallpaper, icon layout and mouse actions under Configure Desktop and Wallpaper.

Panel layouts can be saved and shared. A quick backup of your current layout:

cp ~/.config/plasma-org.kde.plasma.desktop-appletsrc ~/plasma-layout-backup.rc
cp ~/.config/plasmashellrc ~/plasmashellrc-backup

System Settings: what to change first

KRunner, Activities and power features

• KRunner (Alt+Space or just start typing on the desktop) launches apps, finds files, does maths and unit conversion, and runs commands.
• Overview (Meta+W) shows windows and virtual desktops; Meta+Tab cycles Activities.
• Tiling: Meta+T opens the KWin tile editor; hold Shift while dragging a window to snap it into a tile.
• Window rules: right-click a titlebar → More Actions → Configure Special Window Settings to force size, position, desktop or "keep above" for specific apps.
• KDE Connect: pairs your phone for notifications, file transfer and remote input. Open ports 1714–1764 TCP/UDP if you use a firewall.
• Discover installs apps from your distro repos and Flathub, and handles system updates on many distros.

Useful command-line tools

# read and write any KDE config key (Plasma 6 uses the "6" suffix)
kreadconfig6 --file kwinrc --group Windows --key FocusPolicy
kwriteconfig6 --file kdeglobals --group KDE --key SingleClick false
# reload KWin configuration after editing it
qdbus6 org.kde.KWin /KWin reconfigure
# apply a global theme from the terminal
plasma-apply-lookandfeel -l
plasma-apply-lookandfeel -a org.kde.breezedark.desktop
# rebuild the application menu cache
kbuildsycoca6 --noincremental

On some distros qdbus6 is called qdbus-qt6 or qdbus.

Troubleshooting Plasma

Panel disappeared, desktop frozen or black

systemctl --user restart plasma-plasmashell
# fallback
kquitapp6 plasmashell; kstart plasmashell

This restarts only the shell (panels, desktop, widgets); your open windows stay. If the panel is still missing, a widget may be crashing it. Reset the layout to defaults:

systemctl --user stop plasma-plasmashell
mv ~/.config/plasma-org.kde.plasma.desktop-appletsrc ~/.config/plasma-org.kde.plasma.desktop-appletsrc.bak
systemctl --user start plasma-plasmashell

Windows have no borders or effects are glitchy

That is KWin, the window manager and compositor. On X11 you can restart it with kwin_x11 --replace &. On Wayland, KWin is the session itself, so log out and back in. Toggle compositing with Shift+Alt+F12 on X11.

Login loops back to the login screen

1. Switch to a TTY with Ctrl+Alt+F3 and log in.
2. Check for a full disk (df -h ~) and home ownership (ls -ld ~); either one breaks login. See No space left on device.
3. Read the errors: journalctl --user -b -p err.
4. Test with a fresh configuration by moving the Plasma files aside:

   mkdir ~/plasma-config-backup
   mv ~/.config/plasma* ~/.config/kwin* ~/.config/kdeglobals ~/plasma-config-backup/

   If login now works, restore files one at a time to find the culprit.

High CPU from Baloo file indexing

balooctl6 status
balooctl6 suspend
# or disable it entirely
balooctl6 disable

On distros that still ship the older name, use balooctl. Search in Dolphin and KRunner then no longer finds file contents.

Screen sharing or screenshots fail

Wayland screen capture goes through PipeWire and the portal. Make sure xdg-desktop-portal-kde and pipewire are installed and running: systemctl --user status pipewire xdg-desktop-portal.

Plasma 5 to 6 upgrades

If you upgraded from Plasma 5 (for example Debian 12 to 13, or an older Kubuntu), most settings migrate, but some third-party widgets, global themes and KWin scripts written for Plasma 5 don't load in Plasma 6. Remove them from the panel and find Plasma 6 versions in Get New Widgets. For the Debian path, see upgrade Debian 12 to 13. Prefer GNOME's approach or need something lighter? Compare GNOME customization and Xfce configuration. Official docs: KDE UserBase: Plasma.

Frequently asked questions