Skip to main content
This guide covers building Better Blur DX manually from source. For package installation, see the installation guide.
Important: The effect only works for the exact KWin version it was built for. After a system upgrade, you will need to rebuild the effect.

​
Dependencies

Before building, install the required development packages for your distribution.

​
Core Dependencies

  • CMake (minimum 3.16.0)
  • Extra CMake Modules (ECM)
  • C++ compiler with C++23 support (GCC or Clang)
  • Qt 6 (minimum 6.6.0) - Core, DBus, Gui, Network, OpenGL, Qml, Quick, Widgets
  • KDE Frameworks 6 (minimum 5.240.0)
  • KWin development packages
  • KDecoration3 development packages
  • libepoxy
  • Git (for cloning the repository)

​
Arch Linux

sudo pacman -S base-devel git extra-cmake-modules qt6-tools kwin

​
Debian-based (KDE Neon, Kubuntu, Ubuntu)

sudo apt install -y git cmake g++ extra-cmake-modules qt6-tools-dev kwin-dev \
  libkf6configwidgets-dev gettext libkf6crash-dev libkf6globalaccel-dev \
  libkf6kio-dev libkf6service-dev libkf6notifications-dev libkf6kcmutils-dev \
  libkdecorations3-dev libxcb-composite0-dev libxcb-randr0-dev libxcb-shm0-dev

​
Fedora 41, 42

sudo dnf -y install git cmake extra-cmake-modules gcc-g++ kf6-kwindowsystem-devel \
  plasma-workspace-devel libplasma-devel qt6-qtbase-private-devel qt6-qtbase-devel \
  cmake kwin-devel extra-cmake-modules kwin-devel kf6-knotifications-devel \
  kf6-kio-devel kf6-kcrash-devel kf6-ki18n-devel kf6-kguiaddons-devel libepoxy-devel \
  kf6-kglobalaccel-devel kf6-kcmutils-devel kf6-kconfigwidgets-devel \
  kf6-kdeclarative-devel kdecoration-devel kf6-kglobalaccel kf6-kdeclarative \
  libplasma kf6-kio qt6-qtbase kf6-kguiaddons kf6-ki18n wayland-devel libdrm-devel

​
openSUSE

sudo zypper in -y git cmake-full gcc-c++ kf6-extra-cmake-modules kcoreaddons-devel \
  kguiaddons-devel kconfigwidgets-devel kwindowsystem-devel ki18n-devel \
  kiconthemes-devel kpackage-devel frameworkintegration-devel kcmutils-devel \
  kirigami2-devel "cmake(KF6Config)" "cmake(KF6CoreAddons)" \
  "cmake(KF6FrameworkIntegration)" "cmake(KF6GuiAddons)" "cmake(KF6I18n)" \
  "cmake(KF6KCMUtils)" "cmake(KF6KirigamiPlatform)" "cmake(KF6WindowSystem)" \
  "cmake(Qt6Core)" "cmake(Qt6DBus)" "cmake(Qt6Quick)" "cmake(Qt6Svg)" \
  "cmake(Qt6Widgets)" "cmake(Qt6Xml)" "cmake(Qt6UiTools)" "cmake(KF6Crash)" \
  "cmake(KF6GlobalAccel)" "cmake(KF6KIO)" "cmake(KF6Service)" \
  "cmake(KF6Notifications)" libepoxy-devel kwin6-devel

​
Build Steps

​
Standard Build (Wayland)

  1. Clone the repository:
git clone https://github.com/xarblu/kwin-effects-better-blur-dx
cd kwin-effects-better-blur-dx
  1. Create a build directory:
mkdir build
cd build
  1. Configure with CMake:
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
  1. Build the effect:
make -j$(nproc)
  1. Install the effect:
sudo make install
  1. Restart KWin to load the effect:
Log out and log back in, or restart the Plasma session.

​
Building for X11

To build for KWin X11 instead of Wayland, add the BETTERBLUR_X11 option to the CMake configuration: 
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DBETTERBLUR_X11=ON
Then proceed with the build and install steps as normal.
X11 support is deprecated and not extensively tested. The X11 version requires explicit opt-in and may not receive all features going forward.

​
CMake Options

​
BETTERBLUR_X11

Type: Boolean (ON/OFF)
Default: OFF Builds the effect for KWin X11 instead of KWin Wayland. 
cmake .. -DBETTERBLUR_X11=ON
When enabled:
  • Links against KWinX11::kwin instead of KWin::kwin
  • Installs to ${KDE_INSTALL_PLUGINDIR}/kwin-x11/effects/plugins
  • Defines the BETTERBLUR_X11 preprocessor macro
When disabled (default):
  • Links against KWin::kwin
  • Installs to ${KDE_INSTALL_PLUGINDIR}/kwin/effects/plugins

​
CMAKE_INSTALL_PREFIX

Type: Path
Default: System-dependent (usually /usr/local) Specifies the installation prefix. Use /usr for system-wide installation: 
cmake .. -DCMAKE_INSTALL_PREFIX=/usr

​
CMAKE_BUILD_TYPE

Type: String (Release/Debug)
Default: Release Controls the build type. Release builds include optimizations and disable debug output: 
cmake .. -DCMAKE_BUILD_TYPE=Debug

​
Building for Different Distributions

​
Fedora Kinoite (Immutable System)

On Fedora Kinoite and other immutable distributions, build inside a container and create an RPM package: 
# Enter a toolbox container first
toolbox enter

# Clone and build
git clone https://github.com/xarblu/kwin-effects-better-blur-dx
cd kwin-effects-better-blur-dx
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make -j$(nproc)

# Create RPM package
cpack -V -G RPM

# Exit container
exit

# Install the package
sudo rpm-ostree install kwin-effects-better-blur-dx/build/kwin-better-blur-dx.rpm
After installation, reboot to load the new package.

​
NixOS

For NixOS users, use the provided flake instead of building manually. See the Installation guide for details.

​
Rebuilding

Critical: Always remove the build directory when rebuilding the effect, especially after updating the source code or after a system upgrade.
When rebuilding: 
cd kwin-effects-better-blur-dx
rm -rf build
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make -j$(nproc)
sudo make install
This ensures CMake reconfigures properly and detects the current KWin version. Failing to remove the build directory can result in the effect not loading or crashing KWin.

​
Post-Installation

After installation:
  1. Restart KWin: Log out and log back in to load the updated effect. The initial installation doesn’t require this, but updates do.
  2. Enable the effect: Open System Settings > Desktop Effects, disable any existing blur effects, and enable “Better Blur DX”.
  3. Configure settings: Click the settings icon next to Better Blur DX to configure blur strength, corner radius, refraction, and other parameters.

​
Troubleshooting

​
Effect Doesn’t Load

  • Ensure you’ve restarted KWin after installation
  • Check that other blur effects are disabled
  • Verify the effect was built for your current KWin version
  • Check KWin logs: journalctl -b -g kwin

​
Build Fails

  • Ensure all dependencies are installed
  • Remove the build directory and try again
  • Check that your Plasma version is 6.5 or 6.6
  • Verify you have a C++23-capable compiler

​
Version Mismatch After Upgrade

  • Remove the build directory completely
  • Rebuild the effect: rm -rf build && mkdir build && cd build && cmake .. -DCMAKE_INSTALL_PREFIX=/usr && make -j$(nproc) && sudo make install
  • Restart KWin

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us