Quarkus Desktop

Quarkus Desktop brings AWT, Swing and SWT desktop (GUI) applications to Quarkus, in JVM mode and as GraalVM native executables.

The Quarkus core extension io.quarkus:quarkus-awt supports headless Java2D, ImageIO and fonts, which server side applications need. The Desktop AWT and Desktop Swing extensions build on it (they include it) and add what GUI applications need: windows, printing, data transfer, input methods, sound, accessibility, and Swing. The Desktop SWT extension brings Eclipse SWT applications, with the native widgets of Windows, GTK and macOS: it does not need AWT.

Installation

Add one of the extensions to your build file. quarkus-desktop-swing includes quarkus-desktop-awt; quarkus-desktop-swt does not depend on them.

AWT

Maven

<dependency>
    <groupId>io.quarkiverse.desktop</groupId>
    <artifactId>quarkus-desktop-awt</artifactId>
    <version>0.2.1</version>
</dependency>

Gradle

implementation("io.quarkiverse.desktop:quarkus-desktop-awt:0.2.1")

Swing

Maven

<dependency>
    <groupId>io.quarkiverse.desktop</groupId>
    <artifactId>quarkus-desktop-swing</artifactId>
    <version>0.2.1</version>
</dependency>

Gradle

implementation("io.quarkiverse.desktop:quarkus-desktop-swing:0.2.1")

SWT

Maven

<dependency>
    <groupId>io.quarkiverse.desktop</groupId>
    <artifactId>quarkus-desktop-swt</artifactId>
    <version>0.2.1</version>
</dependency>

Maven adds the SWT jar of the platform of the build (org.eclipse.platform:org.eclipse.swt.<ws>.<os>.<arch>) through the profiles of the org.eclipse.platform:org.eclipse.swt pom. Gradle does not apply them: add the SWT jar of the platform yourself, for instance on Windows x64:

Gradle

implementation("io.quarkiverse.desktop:quarkus-desktop-swt:0.2.1")
implementation("org.eclipse.platform:org.eclipse.swt.win32.win32.x86_64:3.132.0")

See Installation for a Gradle build that chooses the jar from the platform of the build, and SWT versions for other SWT releases.

Supported platforms

AWT and Swing applications:

Platform JVM mode Native executable

Platform	JVM mode	Native executable
Windows x64	Yes	Yes: a native build on Windows, with Visual Studio (the C++ build tools). The executable is DPI aware, has the visual styles of Windows, can be a GUI application without console, and comes with the JDK libraries and the Visual C++ runtime it needs (see Windows). Verified with the showcase (see Verification): every page renders the same pixels and gives the same checks as in JVM mode, with the Direct3D, GDI and OpenGL pipelines at 100 % scale, and at 150 % with GDI (with Direct3D at a fractional scale, a few edge pixels of the Metal gradients vary from one run to the next, in JVM mode too: see the showcase README).
Windows arm64	Yes	No: GraalVM has no native image builder for Windows on arm64. JVM mode is verified with the showcase (two JVM runs compared).
Linux x64 and arm64	Yes	Yes: a native build on Linux or in a container. The executable uses the X11 libraries of the system (XWayland on Wayland), GTK 3 for the GTK look and feel and the native dialogs, CUPS and ALSA (see Linux). Verified on both architectures with the showcase (native builds and runs).
macOS (Apple silicon)	Yes	Yes, with Quarkus 4.0.0.Beta1 or later, whose `quarkus-awt` supports macOS, and GraalVM 25.1 or later (see macOS). Verified with the showcase on an Apple silicon Mac.

Windows x64

Yes

Yes: a native build on Windows, with Visual Studio (the C++ build tools). The executable is DPI aware, has the visual styles of Windows, can be a GUI application without console, and comes with the JDK libraries and the Visual C++ runtime it needs (see Windows). Verified with the showcase (see Verification): every page renders the same pixels and gives the same checks as in JVM mode, with the Direct3D, GDI and OpenGL pipelines at 100 % scale, and at 150 % with GDI (with Direct3D at a fractional scale, a few edge pixels of the Metal gradients vary from one run to the next, in JVM mode too: see the showcase README).

Windows arm64

Yes

No: GraalVM has no native image builder for Windows on arm64. JVM mode is verified with the showcase (two JVM runs compared).

Linux x64 and arm64

Yes

Yes: a native build on Linux or in a container. The executable uses the X11 libraries of the system (XWayland on Wayland), GTK 3 for the GTK look and feel and the native dialogs, CUPS and ALSA (see Linux). Verified on both architectures with the showcase (native builds and runs).

macOS (Apple silicon)

Yes

Yes, with Quarkus 4.0.0.Beta1 or later, whose quarkus-awt supports macOS, and GraalVM 25.1 or later (see macOS). Verified with the showcase on an Apple silicon Mac.

Native executables need GraalVM for JDK 25 and Quarkus 3.40.1 or later (on macOS: GraalVM 25.1 or later, and Quarkus 4.0.0.Beta1 or later).

SWT applications (see Platforms of Desktop SWT):

Platform JVM mode Native executable

Platform	JVM mode	Native executable
Windows x64	Yes	Yes: a native build on Windows, with Visual Studio (see Windows). Verified locally with the integration tests of the extension on Windows 11, also with exact reachability metadata: the native executable renders the same pixels as JVM mode, as in the cycles of the SWT variant of the showcase.
Linux x64 and arm64	Yes	Yes: a native build on Linux or in a container, with GTK 3 at run time (see Linux). Verified the same way, with exact reachability metadata, on Ubuntu 24.04 in Docker (X11 under Xvfb, and Wayland, a headless Weston), together with the cycles of the SWT variant of the showcase on x64. On arm64, a native executable built in a container from macOS ran too.
macOS (Apple silicon)	With `-XstartOnFirstThread`	Yes: the event loop runs on the first thread of the process (see macOS). Verified the same way, with exact reachability metadata, on macOS 27.0, together with the cycles of the SWT variant of the showcase.
Windows arm64	Yes	No arm64 executable: GraalVM has no native image builder for Windows on arm64. An x64 executable, built with an x64 GraalVM under the x64 emulation of Windows, runs there under emulation (see Windows). JVM mode is verified with the integration tests of the extension (arm64 JDKs 17 and 25, SWT 3.132.0 and 3.135.0) and the SWT variant of the showcase (two JVM runs compared).

Windows x64

Yes

Yes: a native build on Windows, with Visual Studio (see Windows). Verified locally with the integration tests of the extension on Windows 11, also with exact reachability metadata: the native executable renders the same pixels as JVM mode, as in the cycles of the SWT variant of the showcase.

Linux x64 and arm64

Yes

Yes: a native build on Linux or in a container, with GTK 3 at run time (see Linux). Verified the same way, with exact reachability metadata, on Ubuntu 24.04 in Docker (X11 under Xvfb, and Wayland, a headless Weston), together with the cycles of the SWT variant of the showcase on x64. On arm64, a native executable built in a container from macOS ran too.

macOS (Apple silicon)

With -XstartOnFirstThread

Yes: the event loop runs on the first thread of the process (see macOS). Verified the same way, with exact reachability metadata, on macOS 27.0, together with the cycles of the SWT variant of the showcase.

Windows arm64

Yes

No arm64 executable: GraalVM has no native image builder for Windows on arm64. An x64 executable, built with an x64 GraalVM under the x64 emulation of Windows, runs there under emulation (see Windows). JVM mode is verified with the integration tests of the extension (arm64 JDKs 17 and 25, SWT 3.132.0 and 3.135.0) and the SWT variant of the showcase (two JVM runs compared).

The SWT native executables are verified with GraalVM for JDK 25, with SWT 3.132.0 (and 3.135.0 on Linux x64 and macOS), see Verification of Desktop SWT.

Guides

Desktop AWT: how the extensions work, writing a desktop application, and building native executables.
Desktop Swing: look and feels, text, Synth, and what Swing applications need in native executables.
Desktop SWT: SWT applications in JVM mode and as native executables, and their application model: the startup and the exit of the user interface, the user interface thread (UiThreadExecutor, UiThread, @RunOnUiThread), WidgetBeans, quit requests, dev mode and tests.
Application model and CDI (AWT and Swing): windows as CDI beans, the startup and the exit of the user interface, the event dispatch thread (EdtExecutor, Edt, @RunOnEdt), the application menu, Finder and Dock events of macOS, dev mode and tests.

Verification

The Quarkus Desktop showcase is an application of 75 pages (about 3800 checks) that exercise the AWT, Java2D, text, image, Swing, look and feel, data transfer, desktop, printing, accessibility, JavaBeans and sound features of the JDK. Its tools run it in JVM mode and as a native executable, render every page to an image and compare the two runs pixel by pixel and check by check, also with exact reachability metadata (see Exact reachability metadata). On Windows (with the Direct3D, GDI and OpenGL pipelines, and with exact reachability metadata), Linux and macOS, every page gives the same result in both runs, except the page that shows where a native executable legitimately differs (its known limitations, see Limitations). It also has a Docker image for the Linux runs, and the steps to verify macOS on a Mac.

The showcase also has an SWT variant: -Dswt builds it into target/swt/, and java tools/Cycle.java <label> --swt compares its JVM mode and native runs (they match on Windows 11 x64, on Linux x64 in Docker and on macOS 27.0, also with exact reachability metadata; on Windows 11 arm64, --jvm-only compares two JVM runs, which match, with 4 checks failing in both runs on a display at 200 %, see the showcase README). The integration tests of the Desktop SWT extension compare the rendering of JVM mode and native executables too, when they run locally: the native jobs of the continuous integration skip the JVM mode tests, and so this comparison (see Verification of Desktop SWT).

Configuration

The properties are fixed when the native executable is built and only apply to native executables (JVM mode uses the java launcher and the JDK as they are), except the run time properties of the application model (quarkus.desktop.awt.startup-event.*, quarkus.desktop.awt.exit-on-last-window-closed, and for SWT quarkus.desktop.swt.startup-event.enabled, quarkus.desktop.swt.exit-on-last-shell-closed and quarkus.desktop.swt.application-name) and quarkus.desktop.swing.look-and-feel, which also apply in JVM mode.

Property Default Description

Property	Default	Description
`quarkus.desktop.awt.startup-event.enabled`	`true`, `false` in tests	Whether `DesktopStartupEvent` is fired, see Testing.
`quarkus.desktop.awt.startup-event.mode`	`auto`	`manual`: the application fires `DesktopStartupEvent` with `DesktopLifecycle.start()`, see Manual mode.
`quarkus.desktop.awt.exit-on-last-window-closed`	`true`	The application stops when its last visible window closes, see Closing windows and exit.
`quarkus.desktop.awt.java-beans.jdk-classes`	`true`	The bean properties of the AWT classes for the JavaBeans API (about 0.3 MB), see JavaBeans.
`quarkus.desktop.awt.exact-reachability-metadata`	detected	The lookups for native executables built with `--exact-reachability-metadata` (about 0.3 MB), see Exact reachability metadata.
`quarkus.desktop.awt.windows.dpi-aware`	`true`	Windows: the executable scales its user interface to the display, as the `java` launcher does.
`quarkus.desktop.awt.windows.manifest`	`true`	Windows: the application manifest of the `java` launcher (visual styles, DPI awareness).
`quarkus.desktop.awt.windows.subsystem`	`console`	Windows: `windows` for a GUI application without console window (as `javaw`).
`quarkus.desktop.awt.windows.copy-vc-runtime`	`true`	Windows: copies the Visual C++ runtime next to the executable.
`quarkus.desktop.awt.windows.font-configuration`	`jdk`	Windows: the font configuration of the JDK (all the languages), or `minimal` (Latin only).
`quarkus.desktop.awt.windows.access-bridge`	`true`	Windows: the Java Access Bridge for screen readers.
`quarkus.desktop.awt.macos.park-main-thread`	`true`	macOS: the first thread runs the Cocoa event loop, the application runs on a new thread named `main`. Ignored when the application has an SWT user interface, see Using AWT or Swing with SWT.
`quarkus.desktop.awt.macos.main-thread-stack-size`	`8M`	macOS: the stack size of that `main` thread.
`quarkus.desktop.awt.macos.exit-halt-timeout`	`10S`	macOS: how long `System.exit` may take before the process is halted.
`quarkus.desktop.awt.macos.application-name`	`quarkus.application.name`	macOS: the name of the application in the menu bar and the Dock.
`quarkus.desktop.awt.macos.info-plist`	`false`	macOS: embeds an information property list in the executable.
`quarkus.desktop.awt.macos.jdk-build-version`	`true`	macOS: the executable declares the minimum macOS version and SDK version of the `java` launcher of the JDK (the look of the windows depends on them), see macOS.
`quarkus.desktop.swing.look-and-feel`		The look and feel set at startup (`system`, `cross-platform`, `nimbus`… or a class name), see Look and feel.
`quarkus.desktop.swing.included-look-and-feels`	`all`	The look and feels of the JDK included in the executable (about 10 MB for all of them).
`quarkus.desktop.swing.java-beans.jdk-classes`	`false`	The bean properties of the Swing classes for the JavaBeans API (3 to 4 MB), see JavaBeans.
`quarkus.desktop.swt.startup-event.enabled`	`true`, `false` in tests	Whether the SWT user interface runs (`SwtStartupEvent`), see Testing.
`quarkus.desktop.swt.exit-on-last-shell-closed`	`true`	The application stops when its last visible shell closes, see Closing shells and exit.
`quarkus.desktop.swt.application-name`	`quarkus.application.name` of the build	The name of the application given to SWT (`Display.setAppName`): the menu bar and the Dock on macOS, the `WM_CLASS` of the windows on Linux. Overriding `quarkus.application.name` at run time does not change it, see Configuration of Desktop SWT.
`quarkus.desktop.swt.native-libraries`	`embedded`	The native libraries of SWT: embedded in the executable (SWT extracts them on the first run), or `next-to-executable`, see Native libraries.
`quarkus.desktop.swt.windows.subsystem`	`console`	Windows: `windows` for an SWT application without console window (as `javaw`).
`quarkus.desktop.swt.macos.jdk-build-version`	`true`	macOS: the executable declares the minimum macOS version and SDK version of the `java` launcher of the JDK (the look of the windows depends on them). Ignored with the Desktop AWT extension, see macOS.

quarkus.desktop.awt.startup-event.enabled

true, false in tests

Whether DesktopStartupEvent is fired, see Testing.

quarkus.desktop.awt.startup-event.mode

auto

manual: the application fires DesktopStartupEvent with DesktopLifecycle.start(), see Manual mode.

quarkus.desktop.awt.exit-on-last-window-closed

true

The application stops when its last visible window closes, see Closing windows and exit.

quarkus.desktop.awt.java-beans.jdk-classes

true

The bean properties of the AWT classes for the JavaBeans API (about 0.3 MB), see JavaBeans.

quarkus.desktop.awt.exact-reachability-metadata

detected

The lookups for native executables built with --exact-reachability-metadata (about 0.3 MB), see Exact reachability metadata.

quarkus.desktop.awt.windows.dpi-aware

true

Windows: the executable scales its user interface to the display, as the java launcher does.

quarkus.desktop.awt.windows.manifest

true

Windows: the application manifest of the java launcher (visual styles, DPI awareness).

quarkus.desktop.awt.windows.subsystem

console

Windows: windows for a GUI application without console window (as javaw).

quarkus.desktop.awt.windows.copy-vc-runtime

true

Windows: copies the Visual C++ runtime next to the executable.

quarkus.desktop.awt.windows.font-configuration

jdk

Windows: the font configuration of the JDK (all the languages), or minimal (Latin only).

quarkus.desktop.awt.windows.access-bridge

true

Windows: the Java Access Bridge for screen readers.

quarkus.desktop.awt.macos.park-main-thread

true

macOS: the first thread runs the Cocoa event loop, the application runs on a new thread named main. Ignored when the application has an SWT user interface, see Using AWT or Swing with SWT.

quarkus.desktop.awt.macos.main-thread-stack-size

8M

macOS: the stack size of that main thread.

quarkus.desktop.awt.macos.exit-halt-timeout

10S

macOS: how long System.exit may take before the process is halted.

quarkus.desktop.awt.macos.application-name

quarkus.application.name

macOS: the name of the application in the menu bar and the Dock.

quarkus.desktop.awt.macos.info-plist

false

macOS: embeds an information property list in the executable.

quarkus.desktop.awt.macos.jdk-build-version

true

macOS: the executable declares the minimum macOS version and SDK version of the java launcher of the JDK (the look of the windows depends on them), see macOS.

quarkus.desktop.swing.look-and-feel

The look and feel set at startup (system, cross-platform, nimbus… or a class name), see Look and feel.

quarkus.desktop.swing.included-look-and-feels

all

The look and feels of the JDK included in the executable (about 10 MB for all of them).

quarkus.desktop.swing.java-beans.jdk-classes

false

The bean properties of the Swing classes for the JavaBeans API (3 to 4 MB), see JavaBeans.

quarkus.desktop.swt.startup-event.enabled

true, false in tests

Whether the SWT user interface runs (SwtStartupEvent), see Testing.

quarkus.desktop.swt.exit-on-last-shell-closed

true

The application stops when its last visible shell closes, see Closing shells and exit.

quarkus.desktop.swt.application-name

quarkus.application.name of the build

The name of the application given to SWT (Display.setAppName): the menu bar and the Dock on macOS, the WM_CLASS of the windows on Linux. Overriding quarkus.application.name at run time does not change it, see Configuration of Desktop SWT.

quarkus.desktop.swt.native-libraries

embedded

The native libraries of SWT: embedded in the executable (SWT extracts them on the first run), or next-to-executable, see Native libraries.

quarkus.desktop.swt.windows.subsystem

console

Windows: windows for an SWT application without console window (as javaw).

quarkus.desktop.swt.macos.jdk-build-version

true

macOS: the executable declares the minimum macOS version and SDK version of the java launcher of the JDK (the look of the windows depends on them). Ignored with the Desktop AWT extension, see macOS.

See the configuration reference for the details.