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:

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

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.