How Java Developers Should Run Quarkus on Windows

A production-ready local setup using WSL2 and Podman

I meet many Java developers who want to try Quarkus on their Windows machine but run into the same friction. Java setup feels clunky. Container engines behave differently. Environment variables break Dev Services. File systems slow down build times.

After helping colleagues and readers fix their setups many times, I now recommend one workflow. It is stable, predictable, and easy to maintain long term.

This tutorial shows every command you need to create a productive Quarkus environment on Windows using:

• WSL2 for a Linux-like development environment

• SDKMAN for clean Java version management

• Quarkus CLI for project creation and dependency management

• Podman Desktop for containers and Dev Services

By the end, you will run a Quarkus application in dev mode with live reload and optionally build a native image.

Let’s go step by step.

Install SDKMAN using WSL2

Quarkus works best in a Unix-like environment. WSL2 gives you that environment without switching operating systems. SDKMAN installs cleanly inside WSL2 and avoids the fragile Windows environment variable dialogs.

We start by preparing WSL2.

Enable WSL2

Open PowerShell as Administrator and run:

wsl --install

If WSL is already installed, verify you have a distribution such as Ubuntu.

Restart if prompted.

Now open Ubuntu from the Start Menu.

Step 2: Install SDKMAN

In the Ubuntu terminal:

curl -s "https://get.sdkman.io" | bash

When the script finishes:

source "$HOME/.sdkman/bin/sdkman-init.sh"

SDKMAN is now active inside WSL.

Step 3: Install Java

Install the current LTS (Temurin 21):

sdk install java 21.0.9-tem

Verify:

java -version

This prints your installed JDK version.

Why this works: SDKMAN manages JAVA_HOME and PATH inside WSL without touching Windows settings. Learn more about temurin and Adoptium.

Install the Quarkus CLI

The Quarkus CLI gives you a smooth workflow for creating, running, and managing Quarkus applications. Since SDKMAN is already installed, the CLI installation is simple.

Step 1: Install the CLI

sdk install quarkus

Step 2: Verify it

quarkus --version

You should see Quarkus 3.x.x.

Install and Configure Podman on Windows

Quarkus Dev Services rely on containers. Podman is an open source, daemonless alternative to Docker and works well on Windows with WSL2 support.

Step 1: Install Podman Desktop

1. Download the Windows installer from https://podman-desktop.io

2. Run the installer

3. Launch Podman Desktop

It detects WSL2 automatically.

Step 2: Initialize the Podman Machine

In Podman Desktop:

• Click Set up when prompted

• Confirm when it asks to create a Podman machine

• Wait for the Running (green) status in the bottom right

Your container engine is now ready.

Optional: Enable Docker compatibility

Some Java tools still expect a Docker socket. Podman can emulate this.

Open PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
podman system service --time=0 tcp:localhost:2375

If Quarkus ever reports:

Docker daemon not found

enable “Docker Compatibility Mode” from Podman Desktop settings.

Create and Run Your First Quarkus Application

Now that the environment is ready, we will create a simple application and prove that Quarkus, WSL, and Podman work together.

Step 1: Create the app

Return to your Ubuntu terminal.

Pick a directory inside your Linux file system, not /mnt/c, to avoid slow I/O:

cd ~
quarkus create app com.acme:getting-started
cd getting-started

The directory now contains a full Quarkus project.

Step 2: Run in dev mode

This is the step that shows the value of Quarkus. Live reload, fast startup, and integrated Dev Services all work here.

quarkus dev

When it says “Started”, open: http://localhost:8080

You should see the Quarkus welcome page.

Step 3: Test live reload

Keep the dev mode terminal open.

1. Open the folder in your IDE

   • IntelliJ can open WSL paths directly

   • VS Code requires the Remote WSL extension

2. Edit the file:

src/main/java/com/acme/GreetingResource.java

3. Change the return value:

return “Hello from Windows!”;

4. Save.

Reload the browser. The change appears instantly.

You did not restart the server. This is Quarkus live reload.

Step 4: Optional native build

If you want a native executable:

quarkus build --native -Dquarkus.native.container-build=true

Quarkus uses your Podman machine to run the build inside a Linux container.

Note: You can not run this on windows. It is a Linux native executable. Learn more in this blog post.

Windows-specific troubleshooting

These are common issues I see when helping developers set up Quarkus on Windows. Fixing them early avoids frustration later.

Slow builds or indexing

Cause: Project is located under /mnt/c/...

Fix: Always keep your Quarkus projects inside the Linux file system, for example:

~/projects/my-app

Container runtime not found

Cause: Podman Desktop is not running or Docker compatibility is off

Fixes:

• Ensure Podman Desktop is open

• Ensure the Podman machine is running

WSL uses too much memory

Create:

C:\Users\<YourUser>\.wslconfig

Add:

[wsl2]
memory=4GB

Restart WSL:

wsl --shutdown

What you have now

You now have a clean and productive Quarkus environment on Windows:

• Java managed by SDKMAN

• Quarkus CLI ready for fast scaffolding

• Podman integrated with WSL2 for Dev Services

• A working Quarkus application with live reload

• Optional native image support

This is the setup I recommend for all Windows developers building modern Java, cloud, and AI-infused applications.

Next steps

You can continue exploring Quarkus by adding extensions. For example:

quarkus ext add hibernate-orm-panache
quarkus ext add jdbc-postgresql

Or build container images:

quarkus image build

Make sure to check out the other tutorials with Quarkus!