In this tutorial, you will build your first Quarkus application by using the Quarkus CLI and learn how Quarkus applications are structured. Then, you'll run it first in dev mode with live reload and continuous testing, then run it in JVM mode, and finally run it as a native executable.

Prerequisites

Before you begin, make sure that you have installed a JDK. Use Java version 17 or later.

Consider downloading and installing IBM Semeru Runtimes. Or, you can use Homebrew on Mac or Chocolatey on Windows to install a JDK. (You can install a JDK with choco install temurin17 for Java 17 or choco install temurin21 for Java 21.)

Step 1. Install the Quarkus CLI

The Quarkus CLI is the fastest way to work with Quarkus projects. Instead of manually writing Maven or Gradle commands, the CLI gives you a set of shortcuts designed specifically for Quarkus development.

With the CLI you can:

Create projects quickly without remembering long Maven coordinates.
Add extensions on the fly, such as REST, Hibernate, or LangChain4j.
Run your app in dev mode with a single command (quarkus dev).
Build JVM or native executables without switching tools.

You could do all of this with Maven or Gradle directly, but the CLI provides a much smoother developer experience, especially when you are just starting with Quarkus. It’s also cross-platform and works the same on Linux, macOS, and Windows.

You can install the Quarkus CLI by using:

On MacOS: SDKMAN! or Homebrew
On Windows: Chocolatey or Scoop

Check other installation options in the Quarkus CLI guide.

Installing Quarkus by using Chocolatey on Windows

Chocolatey is a package manager for Windows. You can use Chocolatey to install (and update) the Quarkus CLI.

choco install quarkus

Installing Quarkus by using SDKMan! on MacOS

SDKMAN! can be used to manage development environments. It can manage parallel versions of multiple Software Development Kits on most Unix based systems, making it a good alternative to keep multiple JDK versions handy.

sdk install quarkus

Verifying the installation

Check to make sure that you have the latest version of the Quarkus CLI installed:

quarkus --version

Step 2. Create your first Quarkus project

When you start with Quarkus, you need a project that has the right folders, build files, and example code. You could create all of this by hand, but that is slow and error-prone. Quarkus helps you with project generators that are available per extension. Those project generators scaffold example project content for you.

Creating the project by using the Quarkus CLI

quarkus create app com.ibm.developer:module-one \
    --extension=quarkus-rest

This command creates a new project called “module-one” with the Quarkus REST extension already included.

If you add the switch --no-code, the CLI will not scaffold example Java classes. Instead, it only generates the project structure and configuration files, so you effectively start with a blank project.

Creating the project by using Maven

Alternatively, you can use Maven directly:

mvn io.quarkus:quarkus-maven-plugin:3.29.2:create \
    -DprojectGroupId=com.ibm.developer \
    -DprojectArtifactId=module-one \
    -Dextensions="quarkus-rest"

The version “3.29.2” is the latest Quarkus version at the time of writing. You can check the latest Quarkus version by going to the Quarkus.io website.

Creating the project by using Gradle

Or, you can generate a Gradle project:

quarkus create app com.ibm.developer:module-one \
  --build-tool=gradle \
  --extension=quarkus-rest

Other options for creating Quarkus projects

The Quarkus ecosystem offers even more options to create new projects.

Use the Quarkus project generator website, code.quarkus.io. From this website, you can:
- Select extensions with a simple search box.
- Preview the generated pom.xml.
- Download a .zip file, extract the files locally, and import the folder into your IDE.
  
  This option is great if you want to explore different extensions, see how they affect the generated pom.xml, and download a starter project that matches your needs before you begin coding.
Use your IDE with Quarkus tooling. If you work in VS Code, IntelliJ IDEA, or Eclipse, you can install Quarkus IDE extensions. These plugins let you:
- Create a Quarkus project directly from the IDE’s “New Project” wizard.
- Add extensions from inside the IDE.
- Get live code hints and Quarkus-specific features while you are developing your app.
  
  See the official Quarkus IDE Tooling guide.

Step 3. Explore the project structure

When the project generator finishes, you will see a folder with several files and subfolders. This structure is very similar to a standard Java project, so if you know Maven or Gradle already, it will feel familiar.

Here is what the project looks like (Maven example):

module-one/
 ├── src/
 │   ├── main/
 │   │   ├── java/        # Application source code
 │   │   └── resources/   # Config files like application.properties
 │   └── test/            # Unit and integration tests
 ├── pom.xml              # Maven build file (or build.gradle for Gradle)
 └── README.md

Here is what each part means:

src/main/java/ - This is where you write your application code. All your REST endpoints, services, and business logic will live here.
src/main/resources/ - This folder holds configuration files and static resources.
- application.properties - This is the most important file. In this file, you configure ports, database connections, logging levels, and more.
- You can also store template files or static content if your application needs them.
src/test/java/ - This is where you write tests. Quarkus integrates tightly with JUnit, so you can write both unit and integration tests here.
pom.xml or build.gradle - This is the build descriptor. It tells Maven or Gradle how to build your project, what dependencies to include, and how to package the application. The Quarkus CLI already added the correct Quarkus plugins and extensions.
README.md - A short description file with helpful information about the project.

By using this standard layout, Quarkus makes it easy for any Java developer to jump into a new project. You don’t have to learn a special structure or configuration. So as a Java developer you will feel right at home.

Step 4. Run in developer mode

In traditional Java development, when you change code you usually need to:

Stop the application.
Recompile the project.
Start the application again.

This takes time and breaks your flow. Quarkus solves this problem with developer mode, often called dev mode. In dev mode, you have these capabilities:

Live reload. When you change a file, Quarkus recompiles and reloads the application in less than a second. The change is applied when the application is invoked again. For example, by calling a REST API, refreshing a web UI, or opening the Dev UI. You don’t need to restart manually.
Continuous testing. Your tests run automatically after each change, so you know immediately if something broke.
Dev UI. A special web interface where you can inspect extensions, view configuration, and even run tests from the browser.

To launch your application in dev mode, run this command in your project folder:

quarkus dev

This launches the app with live reload.

Open the Dev UI in your browser: http://localhost:8080/q/dev/. In the Dev UI you can:

See which extensions are active
Manage configuration
Rerun tests interactively

Dev mode gives you fast feedback. Instead of long build cycles, you can code, save, and instantly see the result. This is one of the biggest reasons Quarkus feels lightweight and productive compared to traditional Java frameworks.

The default app includes a simple /hello endpoint so you can verify it runs:

curl http://localhost:8080/hello

Step 5. Build and run in JVM mode

Developer mode is great while you are writing code, but it is not how you usually run applications in production. For real deployments, you package your Quarkus application into a JAR file and run it on the Java Virtual Machine (JVM).

In JVM mode, your application runs on the standard JVM, just like other Java frameworks such as Spring or Jakarta EE. The JVM uses a Just-In-Time (JIT) compiler that can optimize code while the program is running, which often improves performance over time. This mode is the default for Quarkus, and it works well in many scenarios.

Stop dev mode (press Ctrl+C) and package your application:

quarkus build

This command creates a runnable JAR file in the target/quarkus-app/ directory.

Run the application as a standard java executable:

java -jar target/quarkus-app/quarkus-run.jar

Run the following command in a separate terminal to access the app is running on the JVM:

curl http://localhost:8080/hello

JVM mode is a good choice during development because it is simple and flexible. Many organizations also use it in production when they want runtime optimisations from the JIT compiler or when they already have established processes for running Java applications on the JVM.

Step 6. Build and run as a native executable

Quarkus has a special capability that makes it stand out from most Java frameworks: you can compile your application into a native executable. For Java developers, this is important because it unlocks new use cases like serverless functions, high-density microservices on Kubernetes, and even edge devices, which are places where traditional JVM apps might be too slow to start or too heavy on memory.

In native mode, the code is compiled ahead of time into a binary that starts almost instantly and uses very little memory. Native mode is the best choice when you need ultra-fast startup and low memory usage, for example in serverless platforms, Kubernetes pods, or edge devices. For development and testing, most people stay with JVM mode because builds are faster. Native mode is usually used in production when efficiency is more important than build speed.

This works through GraalVM or Mandrel, which are special distributions of the Java toolchain that are designed for native compilation.

If you have installed GraalVM or Mandrel, you can build a native binary with the following command. Make sure to stop the dev mode before you do.

./mvnw package -Dnative
./target/module-one-1.0.0-SNAPSHOT-runner

Notice the much faster startup and smaller memory footprint compared to JVM mode.

You can access this endpoint from another terminal with:

curl http://localhost:8080/hello

Comparing JVM mode and native mode

Now that you have seen both modes, it is easier to understand how they compare.

Applications running in JVM mode take longer to start because the JVM loads classes and compiles them at runtime, but the JIT compiler can optimize performance as the application runs, often leading to higher peak throughput. In contrast, native executables start almost instantly because the code has already been compiled ahead of time, and they use less memory, which makes them ideal for serverless, Kubernetes, and edge environments.

The trade-off is that building a native executable takes more time and consumes more CPU and memory during the build process. In practice, many teams use JVM mode for development and testing because it is faster to build, while using native mode for production scenarios where startup speed and resource efficiency are critical.

Summary

In this tutorial, you learned how the Quarkus CLI streamlines Java development by providing a unified interface for creating projects, managing extensions, and running applications in multiple modes, all without switching between different build tools or memorizing complex Maven commands. You also discovered how Quarkus's developer mode with live reload and its ability to compile to both JVM and native executables gives you the flexibility to optimize for either development speed or production efficiency, making it a powerful choice for modern cloud-native and serverless applications.

Getting started with the Quarkus CLI

Getting started with the Quarkus CLI