1Title: Running and debugging GTK Applications 2Slug: gtk-running 3 4## Environment variables 5 6GTK inspects a number of environment variables in addition to 7standard variables like `LANG`, `PATH`, `HOME` or `DISPLAY`; mostly 8to determine paths to look for certain files. The [X11](#x11-envar), 9[Wayland](#wayland-envar), [Windows](#win32-envar) and 10[Broadway](#broadway-envar) GDK backends use some additional 11environment variables. 12 13### `GTK_DEBUG` 14 15This variable can be set to a list of debug options, which cause GTK to 16print out different types of debugging information. Some of these options 17are only available when GTK has been configured with `-Ddebug=true`. 18 19`actions` 20: Actions and menu models 21 22`builder` 23: GtkBuilder support 24 25`builder-objects` 26: Unused GtkBuilder objects 27 28`geometry` 29: Size allocation 30 31`icontheme` 32: Icon themes 33 34`iconfallback` 35: Information about icon fallback 36 37`keybindings` 38: Keyboard shortcuts 39 40`modules` 41: Modules and extensions 42 43`printing` 44: Printing 45 46`size-request` 47: Size requests 48 49`text` 50: Text widget internals 51 52`tree` 53: Tree widget internals 54 55`constraints` 56: Constraints and the constraint solver 57 58`layout` 59: Layout managers 60 61`acccessibility` 62: Accessibility state changs 63 64A number of keys are influencing behavior instead of just logging: 65 66`interactive` 67: Open the [interactive debugger](#interactive-debugging) 68 69`no-css-cache` 70: Bypass caching for CSS style properties 71 72`touchscreen` 73: Pretend the pointer is a touchscreen device 74 75`snapshot` 76: Include debug render nodes in the generated snapshots 77 78The special value `all` can be used to turn on all debug options. 79The special value `help` can be used to obtain a list of all 80supported debug options. 81 82### `GTK_PATH` 83 84Specifies a list of directories to search when GTK is looking for 85dynamically loaded objects such as input method modules and print 86backends. If the path to the dynamically loaded object is given as 87an absolute path name, then GTK loads it directly. Otherwise, GTK 88goes in turn through the directories in `GTK_PATH`, followed by 89the directory `.gtk-4.0` in the user's home directory, followed 90by the system default directory, which is `libdir/gtk-4.0/modules`. 91(If `GTK_EXE_PREFIX` is defined, `libdir` is `$GTK_EXE_PREFIX/lib`. 92Otherwise it is the libdir specified when GTK was configured, usually 93`/usr/lib`, or `/usr/local/lib`.) 94 95For each directory in this list, GTK actually looks in a subdirectory 96`directory/version/host/type`. Where `version` is derived from the 97version of GTK (use `pkg-config --variable=gtk_binary_version gtk4` 98to determine this from a script), `host` is the architecture on 99which GTK was built. (use `pkg-config --variable=gtk_host gtk4` to 100determine this from a script), and `type` is a directory specific to 101the type of modules; currently it can be `modules`, `immodules` or 102`printbackends`, corresponding to the types of modules mentioned 103above. Either `version`, `host`, or both may be omitted. GTK looks 104first in the most specific directory, then in directories with 105fewer components. 106The components of `GTK_PATH` are separated by the ':' character on 107Linux and Unix, and the ';' character on Windows. 108 109Note that this environment variable is read by GTK 2.x and GTK 3.x 110too, which makes it unsuitable for setting it system-wide (or 111session-wide), since doing so will cause applications using 112different GTK versions to see incompatible modules. 113 114### `GTK_IM_MODULE` 115 116Specifies an IM module to use in preference to the one determined 117from the locale. If this isn't set and you are running on the system 118that enables `XSETTINGS` and has a value in `Gtk/IMModule`, that will 119be used for the default IM module. This also can be a colon-separated 120list of input-methods, which GTK will try in turn until it finds one 121available on the system. 122 123### `GTK_MEDIA` 124 125Specifies what backend to load for [class@Gtk.MediaFile]. The possible values 126depend on what options GTK was built with, and can include 'gstreamer', 127'ffmpeg' and 'none'. If set to 'none', media playback will be unavailable. 128The special value 'help' can be used to obtain a list of all supported 129media backends. 130 131### `GTK_EXE_PREFIX` 132 133If set, GTK uses `$GTK_EXE_PREFIX/lib` instead of the libdir 134configured when GTK was compiled. 135 136### `GTK_DATA_PREFIX` 137 138If set, GTK uses `$GTK_DATA_PREFIX` instead of the prefix 139configured when GTK was compiled. 140 141### `GTK_THEME` 142 143If set, makes GTK use the named theme instead of the theme 144that is specified by the gtk-theme-name setting. This is intended 145mainly for easy debugging of theme issues. 146 147It is also possible to specify a theme variant to load, by appending 148the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`. 149 150The following environment variables are used by GdkPixbuf, GDK or 151Pango, not by GTK itself, but we list them here for completeness 152nevertheless. 153 154### `GDK_PIXBUF_MODULE_FILE` 155 156Specifies the file listing the GdkPixbuf loader modules to load. 157This environment variable overrides the default value 158`libdir/gtk-4.0/4.0.0/loaders.cache` (`libdir` is the sysconfdir 159specified when GTK was configured, usually `/usr/lib`.) 160 161The `loaders.cache` file is generated by the 162`gdk-pixbuf-query-loaders` utility. 163 164### `GDK_DEBUG` 165 166This variable can be set to a list of debug options, which cause GDK to 167print out different types of debugging information. Some of these options 168are only available when GTK has been configured with `-Ddebug=true`. 169 170`cursor` 171: Information about cursor objects (only win32) 172 173`eventloop` 174: Information about event loop operation (mostly macOS) 175 176`misc` 177: Miscellaneous information 178 179`frames` 180: Information about the frame clock 181 182`settings` 183: Information about xsettings 184 185`selection` 186: Information about selections 187 188`clipboard` 189: Information about clipboards 190 191`dnd` 192: Information about drag-and-drop 193 194`opengl` 195: Information about OpenGL 196 197`vulkan` 198: Information about Vulkan 199 200A number of options affect behavior instead of logging: 201 202`nograbs` 203: Turn off all pointer and keyboard grabs 204 205`gl-disable` 206: Disable OpenGL support 207 208`gl-software` 209: Force OpenGL software rendering 210 211`gl-texture-rect` 212: Use the OpenGL texture rectangle extension, if available 213 214`gl-legacy` 215: Use a legacy OpenGL context 216 217`gl-gles` 218: Use a GLES OpenGL context 219 220`vulkan-disable` 221: Disable Vulkan support 222 223`vulkan-validate` 224: Load the Vulkan validation layer, if available 225 226The special value `all` can be used to turn on all debug options. The special 227value `help` can be used to obtain a list of all supported debug options. 228 229### `GSK_DEBUG` 230 231This variable can be set to a list of debug options, which cause GSK to 232print out different types of debugging information. Some of these options 233are only available when GTK has been configured with `-Ddebug=true`. 234 235`renderer` 236: General renderer information 237 238`cairo` 239: cairo renderer information 240 241`opengl` 242: OpenGL renderer information 243 244`shaders` 245: Shaders 246 247`surface` 248: Surfaces 249 250`vulkan` 251: Vulkan renderer information 252 253`fallback` 254: Information about fallbacks 255 256`glyphcache` 257: Information about glyph caching 258 259A number of options affect behavior instead of logging: 260 261`diff` 262: Show differences 263 264`geometry` 265: Show borders 266 267`full-redraw` 268: Force full redraws for every frame 269 270`sync` 271: Sync after each frame 272 273`vulkan-staging-image` 274: Use a staging image for Vulkan texture upload 275 276`vulkan-staging-buffer` 277: Use a staging buffer for Vulkan texture upload 278 279The special value `all` can be used to turn on all debug options. The special 280value `help` can be used to obtain a list of all supported debug options. 281 282### `GDK_BACKEND` 283 284If set, selects the GDK backend to use. Selecting a backend 285requires that GTK is compiled with support for that backend. 286The following backends can be selected, provided they are 287included in the GDK libraries you are using: 288 289`quartz` 290: Selects the native Quartz backend 291 292`win32` 293: Selects the native backend for Microsoft Windows 294 295`x11` 296: Selects the native backend for connecting to X11 servers 297 298`broadway` 299: Selects the Broadway backend for display in web browsers 300 301`wayland` 302: Selects the Wayland backend for connecting to Wayland compositors 303 304This environment variable can contain a comma-separated list of 305backend names, which are tried in order. The list may also contain 306a `*`, which means: try all remaining backends. The special value 307`help` can be used to make GDK print out a list of all available 308backends. For more information about selecting backends, 309see the [func@Gdk.DisplayManager.get] function. 310 311### `GDK_VULKAN_DEVICE` 312 313This variable can be set to the index of a Vulkan device to override 314the default selection of the device that is used for Vulkan rendering. 315The special value `list` can be used to obtain a list of all Vulkan 316devices. 317 318### `GSK_RENDERER` 319 320If set, selects the GSK renderer to use. The following renderers can 321be selected, provided they are included in the GTK library you are 322using and the GDK backend supports them: 323 324`help` 325: Prints information about available options 326 327`broadway` 328: Selects the Broadway-backend specific renderer 329 330`cairo` 331: Selects the fallback Cairo renderer 332 333`opengl` 334: Selects the default OpenGL renderer 335 336`gl` 337: Selects the "gl" OpenGL renderer 338 339`ngl` 340: Selects the "ngl" OpenGL renderer 341 342`vulkan` 343: Selects the Vulkan renderer 344 345### `GTK_CSD` 346 347The default value of this environment variable is `1`. If changed 348to `0`, this disables the default use of client-side decorations 349on GTK windows, thus making the window manager responsible for 350drawing the decorations of windows that do not have a custom 351titlebar widget. 352 353CSD is always used for windows with a custom titlebar widget set, 354as the WM should not draw another titlebar or other decorations 355around the custom one. 356 357### `GTK_A11Y` 358 359If set, selects the accessibility backend to use. The following 360backends can be selected, provided they are included in the GTK 361library you are using: 362 363`help` 364: Prints information about available options 365 366`atspi` 367: Selects the AT-SPI accessibility backend 368 369`test` 370: Selects the test backend 371 372`none` 373: Disables the accessibility backend 374 375The `test` accessibility backend is recommended for test suites and remote 376continuous integration pipelines. 377 378### `XDG_DTA_HOME`, `XDG_DATA_DIRS` 379 380GTK uses these environment variables to locate icon themes 381and MIME information. For more information, see the 382[Icon Theme Specification](https://freedesktop.org/Standards/icon-theme-spec) 383the [Shared MIME-Info Database](https://freedesktop.org/Standards/shared-mime-info-spec) 384and the [Base Directory Specification](https://freedesktop.org/Standards/basedir-spec). 385 386### `DESKTOP_STARTUP_ID` 387 388GTK uses this environment variable to provide startup notification 389according to the [Startup Notification Spec](https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). 390Following the specification, GTK unsets this variable after reading 391it (to keep it from leaking to child processes). So, if you need its 392value for your own purposes, you have to read it before calling 393[func@Gtk.init]. 394 395## Interactive debugging 396 397 398 399GTK includes an interactive debugger, called the GTK Inspector, which 400lets you explore the widget tree of any GTK application at runtime, 401as well as tweak the theme and trigger visual debugging aids. You can 402easily try out changes at runtime before putting them into the code. 403 404Note that the GTK inspector can only show GTK internals. It can not 405understand the application-specific logic of a GTK application. Also, 406the fact that the GTK inspector is running in the application process 407limits what it can do. It is meant as a complement to full-blown 408debuggers and system tracing facilities such as DTrace, not as a 409replacement. 410 411To enable the GTK inspector, you can use the <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> or 412<kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> keyboard shortcuts, or 413set the `GTK_DEBUG=interactive` environment variable. 414 415There are a few more environment variables that can be set to influence 416how the inspector renders its UI. `GTK_INSPECTOR_DISPLAY` and 417`GTK_INSPECTOR_RENDERER` determine the GDK display and the GSK 418renderer that the inspector is using. 419 420In some situations, it may be inappropriate to give users access to 421the GTK inspector. The keyboard shortcuts can be disabled with the 422`enable-inspector-keybinding` key in the `org.gtk.Settings.Debug` 423GSettings schema. 424 425## Profiling 426 427GTK supports profiling with sysprof. It exports timing information 428about frameclock phases and various characteristics of GskRenderers 429in a format that can be displayed by sysprof or GNOME Builder. 430 431A simple way to capture data is to run your application under the 432`sysprof-cli` wrapper, which will write profiling data to a file 433called `capture.syscap`. 434 435When launching the application from sysprof, it will set the 436`SYSPROF_TRACE_FD` environment variable to point GTK at a file 437descriptor to write profiling data to. 438
