Guidelines and HOWTOs/Gammaray

KDAB GammaRay is a graphical inspection tool for applications built with Qt Widgets or Qt Quick (QML). It allows you to introspect a running application at runtime, inspect object trees, properties, models, signals, and more.

Upstream resources:

• Source code: https://github.com/KDAB/GammaRay
• Project page: https://www.kdab.com/gammaray

Video tutorials:

• https://www.youtube.com/watch?v=gjX8vFlur3g
• https://www.youtube.com/watch?v=W6dVfn1nAzI

Requirements

GammaRay and the application being inspected must use the exact same Qt version . A mismatch will usually prevent GammaRay from attaching correctly.

The easiest way to ensure this is to install both GammaRay and the target application from your distribution’s packages.

If you have built Qt yourself (for example using kde-builder) or installed Qt via the Qt Online Installer, you should also build GammaRay yourself using the same Qt.

Building GammaRay with kde-builder

To build GammaRay with kde-builder, add the following to your ~/.config/kde-builder.yaml file:

project gammaray:
  repository: https://github.com/KDAB/GammaRay.git

After that, rebuild as usual.

Running and attaching GammaRay

As an example, assume you have built Qt 6, kcalc, and gammaray using kde-builder.

In one terminal tab, run the application you want to inspect:

kde-builder --run kcalc

In another terminal tab, set up the environment and launch GammaRay:

source ~/kde/build/kconfig/prefix.sh
gammaray

The GammaRay Launcher window will appear. In the Attach tab, select the running process, for example:

/home/user/kde/usr/bin/kcalc

ptrace / debugger attachment issues

GammaRay may fail to attach and show an error similar to:

Launcher Error
gdb: Yama security extension is blocking runtime attaching, see /proc/sys/kernel/yama/ptrace_scope
lldb: The debugger executable 'lldb' could not be found
Uh-oh, there is no default attach injector on this platform.
See https://github.com/KDAB/GammaRay/wiki/Known-Issues for troubleshooting

This is a common Linux security restriction related to ptrace. See: https://github.com/KDAB/GammaRay/wiki/Known-Issues#gdb-method-fails-to-attach-to-running-process

Temporary workaround

You can temporarily relax the restriction (until reboot):

echo 0 > /proc/sys/kernel/yama/ptrace_scope

Permanent configuration (Debian/Ubuntu example)

To disable the restriction permanently:

sudo cp /etc/sysctl.d/10-ptrace.conf /etc/sysctl.d/10-ptrace.conf~orig
sudo nano /etc/sysctl.d/10-ptrace.conf

Replace:

kernel.yama.ptrace_scope = 1

with:

kernel.yama.ptrace_scope = 0

Then reboot your system.

Using GammaRay

Once attached successfully, the window GammaRay (kcalc) will be shown.

• For Qt Widgets applications, start with the Widgets top-level tab.
• For Qt Quick / QML applications, start with the Quick Scenes top-level tab.

Examples:

• kcalc – Qt Widgets application
• kalk – Qt Quick (QML) application

Inspecting a Qt Quick / QML application

For QML-based applications, the most relevant top-level tabs are:

• Quick Scenes – visual QML and Qt Quick object hierarchy
• Models – model objects exposed to QML
• Problems – QML warnings such as binding loops or invisible items

In the Quick Scenes view, a combo box at the top allows you to select which QML window or scene to inspect (for example, a main window versus a settings dialog).

You can right-click on a QML object and jump directly to related tools:

• Show in "Quick Scenes" tool
• Show in "Objects" tool
• Show in "Meta Objects" tool
• Show in "Signals" tool

This makes it easy to navigate between visual elements, underlying QObject instances, and their metadata.