[Feedback Wanted] Experimental GTK4 + WebKitGTK 6.0 Support

[leaanthony]

Note

Status: Merged into v3-alpha

PR #4958 has been merged. Clone from v3-alpha to test this feature.

---

Wails v3 now includes experimental support for GTK4 and WebKitGTK 6.0 on Linux via the -tags gtk4 build flag.

Why GTK4?

• Better Wayland support - Native Wayland rendering without X11 compatibility layer
• Improved performance - GPU-accelerated rendering pipeline
• Modern features - Fractional scaling, HDR support, better HiDPI handling
• Future-proof - GTK3 is in maintenance mode, GTK4 is the future of Linux desktop

---

Getting Started

Step 1: Install System Dependencies

Install GTK4 and WebKitGTK 6.0 development packages:

Distro	Command
Ubuntu/Debian	sudo apt install libgtk-4-dev libwebkitgtk-6.0-dev
Fedora	sudo dnf install gtk4-devel webkitgtk6.0-devel
Arch Linux	sudo pacman -S gtk4 webkitgtk-6.0
openSUSE	sudo zypper install gtk4-devel webkitgtk-6_0-devel
Gentoo	sudo emerge gui-libs/gtk net-libs/webkit-gtk:6
Solus	sudo eopkg install libgtk-4-devel libwebkit-gtk6-devel
NixOS	Add gtk4 and webkitgtk_6_0 to your environment

Step 2: Clone the Repository

git clone -b v3-alpha https://github.com/wailsapp/wails.git
cd wails/v3

Step 3: Verify Installation

go install ./cmd/wails3
wails3 doctor

You should see both GTK3 (required) and GTK4 (experimental/optional) listed.

Step 4: Run the Examples with GTK4

Browse the examples in v3/examples/ and run them with the GTK4 tag:

# List available examples
ls examples/

# Run an example with GTK4
cd examples/menu
go run -tags gtk4 .

# Or build it
go build -tags gtk4 .
./menu

Recommended examples to test:

• examples/menu - Tests menu functionality
• examples/dialogs - Tests file/message dialogs
• examples/drag-n-drop - Tests drag and drop
• examples/window - Tests window management
• examples/events - Tests event handling
• examples/clipboard - Tests clipboard operations

---

What We Need You To Test

🔍 Test 1: Wails Doctor Output

Run wails3 doctor and report:

• Does it correctly detect your GTK3 packages as installed?
• Does it correctly detect your GTK4 packages (if installed)?
• Are the package names correct for your distro?

If doctor shows wrong package names, please tell us:

• Your distribution and version
• Your package manager (apt, dnf, pacman, etc.)
• The correct package names for your system

🪟 Test 2: Window Management

• Window opens correctly
• Window resizing works
• Window minimize/maximize/restore works
• Window close works
• Fullscreen toggle works
• Window dragging works (click and drag title bar area)

📋 Test 3: Menus

• Application menu bar displays
• Menu items are clickable
• Keyboard accelerators work (Ctrl+Q, etc.)
• Checkboxes in menus work
• Radio buttons in menus work
• Submenus work

📁 Test 4: Dialogs

• File Open dialog works
• File Save dialog works
• Folder selection dialog works
• Message/Alert dialogs work

🖱️ Test 5: Drag and Drop

• Dragging files into the window works
• Drop events are received correctly

📊 Test 6: Performance

Compare GTK3 vs GTK4 builds:

• App startup time
• UI responsiveness
• Scrolling smoothness
• Animation performance

🖥️ Test 7: Display

• Correct rendering on your display
• HiDPI/scaling works correctly
• Multiple monitors work

---

How to Report Your Results

Please include this info:

## System Info
- **Distro**: (e.g., Ubuntu 24.04, Fedora 40, Arch)
- **Package Manager**: (apt, dnf, pacman, zypper, emerge, eopkg, nix)
- **Desktop Environment**: (GNOME, KDE, XFCE, Sway, etc.)
- **Window Manager**: (Mutter, KWin, Sway, i3, etc.)
- **Display Server**: Wayland / X11
- **GTK4 Version**: `pkg-config --modversion gtk4`
- **WebKitGTK Version**: `pkg-config --modversion webkitgtk-6.0`

## Test Results
- Doctor output: ✅ / ❌ / ⚠️
- Window management: ✅ / ❌ / ⚠️
- Menus: ✅ / ❌ / ⚠️
- Dialogs: ✅ / ❌ / ⚠️
- Drag and drop: ✅ / ❌ / ⚠️
- Performance: Better / Same / Worse than GTK3
- Display/scaling: ✅ / ❌ / ⚠️

## Details
[Any specific issues, error messages, or observations]

---

Reporting Bugs

Please use sub-issues to report specific bugs. This keeps everything organized under this parent issue.

To create a sub-issue:

1. Click "Create sub-issue" below
2. Use [GTK4] prefix in the title (e.g., [GTK4] Menu accelerators not working on KDE Wayland)
3. Include your system info and steps to reproduce

---

Contributing Fixes

PRs welcome! Please:

1. Target the v3-alpha branch
2. Test with both default (GTK3) and -tags gtk4 builds
3. Reference this issue in your PR

---

Known Limitations

Limitation	Reason
Window positioning on Wayland	Wayland protocol doesn't allow arbitrary positioning
ShowHiddenFiles() in file dialogs	GTK4 uses portal-based dialogs controlled by DE
CanCreateDirectories()	Same as above - portal controls this
X11 performance may vary	GTK4 is optimized primarily for Wayland

Related

• Original feature request: Upgrade to webkitgtk-6.0 #3193
• Implementation tracker: See IMPLEMENTATION.md in repo
• Pull Request: feat(linux): GTK4 + WebKitGTK 6.0 support (opt-in via -tags gtk4) #4958

---

Thank you for helping test GTK4 support! Your feedback directly shapes whether this becomes the default in a future release.

[lleyton]

System Info

• Distro: Fedora Linux Asahi Remix
• Package Manager: dnf
• Desktop Environment: KDE
• Window Manager: KWin
• Display Server: Wayland
• GTK4 Version: 4.20.3
• WebKitGTK Version: 2.50.4

Test Results

• Doctor output: ✅
• Window management: ✅
• Menus: ✅
• Dialogs: ✅
• Drag and drop: ✅
• Performance: Sameish, maybe a little better
• Display/scaling: ✅, unable to test multiple monitors

[catthou]

System Info

• Distro: Gentoo Linux kernel 6.6.116
• Package Manager: emerge
• Desktop Environment: Openbox (WM) + Xcompmgr (compositor)
• Window Manager: Openbox
• Display Server: X11
• GTK4 Version: 4.18.6
• WebKitGTK Version: 2.48.5

Test Results

• Doctor output: ⚠️
• Window management: ⚠️
• Menus: ✅
• Dialogs: ✅
• Drag and drop: ✅
• Performance: N/A, Have not tested other versions but also haven't noticed any performance issues
• Display/scaling: ⚠️

Details

Doctor Output: I don't see any output in doctor about gtk packages (dependencies only lists npm and docker) but I presume it works because the end message is No issues found and Your system is ready for Wails development!

However, when running the tests, they properly report: INF Platform Info: ID=gentoo Name=Gentoo Version=2.18 Branding="" GTK=4.18.6 WebKitGTK=2.48.5

Window Management: None of the disable minimize/maximize/close in the window test stops my title bar buttons from working. Note, does not use Gtk4 titlebar so maybe these buttons work for that. On the other hand, in the events test, the Close Window event properly intercepts me trying to close the window via window decorations and shows the "Window 1 closing? Nope!" message.

Hide (for 2 seconds) sometimes unhides the window in a minimized state and sometimes restores it to visibility properly.

Setting and getting window position doesn't work at all - window location is always reported as 0, 0.

Minimum window size is the size of the menu bar. Setting any minimum window size sets minimum size to 410x200, resetting minimum window size doesn't do anything. Setting maximum window size does nothing.

Drag and Drop: Note, does not use gtk4 titlebar

Display/Scaling: Tests open at exactly stated window size, disregarding my 1.25 requested scaling, but this is consistent with my setup; Qt applications and a few other toolkits respect my config, gtk4 never has.

In the window test, clicking on the Urls gives me:

pci id for fd 27: 10de:1c03, driver (null)
pci id for fd 28: 10de:1c03, driver (null)
kmsro: driver missing
KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission denied
KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission denied
Failed to create GBM buffer of size 800x572: Permission denied

And it occurs to me now that maybe the windows aren't supposed to display white screens? They all show that message when they startup, and no window content besides the menu or title bars.

[leaanthony]

@catthou - Amazing report. Thank you 🙏 I'm guessing the white screen is related to nvidia drivers?

[COD3HUNT3R]

Build with tags support for wails3 build command like v2?

wails3 build -tags gtk4

  ERROR   Error: flag provided but not defined: -tags
          See 'wails build --help' for usage

Currently doing this on taskfiles but for one time build or testing this would be great.

[leaanthony]

Build with tags support for wails3 build command like v2?

wails3 build -tags gtk4

  ERROR   Error: flag provided but not defined: -tags
          See 'wails build --help' for usage

Nice improvement! Did you also just run the examples with the tag?

[leaanthony]

@catthou Thanks for the detailed report! Regarding the white screens and GPU errors:

pci id for fd 27: 10de:1c03, driver (null)
KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission denied
Failed to create GBM buffer of size 800x572: Permission denied

This looks like a GPU acceleration issue with NVIDIA on X11. WebKitGTK is trying to use hardware-accelerated rendering (GBM/DRM) but can't access the DRM render nodes. A couple of things to try:

1. Set GPU policy to software rendering - In your window options, set WebviewGpuPolicy: application.WebviewGpuPolicyNever in LinuxWindow. This disables hardware acceleration and should fix the white screens:

   app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
       Linux: application.LinuxWindow{
           WebviewGpuPolicy: application.WebviewGpuPolicyNever,
       },
   })

2. Check DRM permissions - Make sure your user is in the video and render groups:

   groups  # check current groups
   sudo usermod -aG video,render $USER  # add if missing, then re-login

3. Check render nodes - Verify /dev/dri/renderD128 exists and is accessible:

   ls -la /dev/dri/

The default GPU policy in the GTK4 backend is ALWAYS (hardware acceleration). For NVIDIA on X11 with Gentoo, software rendering may be the more reliable option until the driver situation improves.