How to Use Quarkus Almanac: The Beginner's Guide to Upgrade Reviews
CodexFuse Team · 2026-11-02T15:35:39.233Z · 18 min read min read
Quarkus Almanac compares two framework releases on config, dependencies, extensions, and Java APIs. Learn to run your first comparison, use the CLI, and plan your Quarkus 3 to 4 upgrade.
Upgrading a Java framework is the kind of job that looks small on the calendar and eats a week in practice. You bump the version, the build passes, and then production behaves differently — because a config property vanished, a managed dependency moved, or an extension you relied on quietly changed status. If you are searching for how to use Quarkus Almanac, you have found the tool built to take that guesswork out: a release-comparison service from the Quarkus project, announced October 29, 2026, that puts two framework releases side by side and shows you exactly what changed in extensions, Java APIs, configuration properties, and managed dependencies. This beginner's guide — a full quarkus almanac tutorial — walks through the mental model, your first comparison on the site, the platform-vs-core BOM switch most beginners miss, and the Java CLI for people who want the data locally. If you containerize your Java services, our Docker beginner guide pairs well with the upgrade planning here.
What Is the Quarkus Almanac, Exactly?
The Quarkus Almanac is a release-diffing tool for the Quarkus framework: pick any two Quarkus releases and it shows you the differences in config properties, managed dependencies, extensions, and the API of the classes in the Quarkus jars. If your search was literally "what is quarkus almanac" — that sentence is the whole answer. It is modeled on the Java Version Almanac (javaalmanac.io), and its job is to turn upgrade review from archaeology into a checklist. The website lives at https://quarkus.io/almanac/, and it is a static site: your browser computes every comparison from a dataset published in the quarkusio/almanac GitHub repository, refreshed by an automated workflow every twelve hours. A Java command-line tool does the heavy lifting behind the scenes, extracting the data from the artifacts Quarkus publishes on Maven Central.
The one mental-model lesson to lock in before anything else: the Almanac does not upgrade your project for you, and it does not rewrite your config. It is a quarkus upgrade review tool — it tells you precisely what changed between the release you run and the release you want, so the upgrade itself becomes deliberate instead of hopeful. Everything in this guide builds on that distinction.
How Do You Use the Quarkus Almanac, Step by Step?
Seven steps take you from zero to a finished upgrade review: open the site, pick your two releases, read the summary, work through the four comparison sections, switch the BOM comparison, and drill into the per-item history pages.
- Open the Almanac site. Go to https://quarkus.io/almanac/ — no account, no install, no login. The home page offers quick comparisons between popular release pairs, including comparisons between two LTS releases, which is the review most teams actually need.
- Pick your two releases. Enter the version you currently run and the version you are evaluating. The Almanac covers every Quarkus release whose BOM is on Maven Central, from 0.11.0 onward, including pre-releases. (Very early releases had no BOM, so 0.0.1, 0.1.0, and the canceled 0.9.0 are out of range — the README is precise where the announcement was loose.)
- Read the comparison summary first. Every comparison opens with a summary that counts the changes of each kind — how many config properties changed, how many dependencies moved, how many extensions differ, how many API items changed. Treat this like triage: it tells you which sections deserve your time.
- Work the Configuration section. This is where most upgrade surprises live: properties added or removed, defaults changed, types changed, accepted values changed, phase changed, or deprecated. Items are grouped by extension and filterable by property, extension, or description.
- Work the Dependencies and Extensions sections. Check the dependency deltas for upgrades, downgrades, additions, and removals, then confirm your extensions still exist with the same status in the target release.
- Check the Platform BOM switch. Decide whether you are comparing platform BOMs or core BOMs (explained in full below) — this one toggle changes the dependency story completely, and beginners almost always read the wrong one first.
- Drill into history pages. Every config property, managed artifact, and class has its own history page. Use them to confirm exactly when a change landed before you blame the wrong release.
What Does the Almanac Compare Between Two Releases?
The Almanac compares four dimensions of a release, and each one gets its own section on the results page. Sections start collapsed, so you open them in the order that matters for your upgrade.
| Comparison dimension | What it shows you | The upgrade question it answers |
|---|---|---|
| Configuration properties | Properties added, removed, or changed (default value, type, accepted values, phase), plus deprecations — grouped by extension, filterable by name, extension, or description | Will my application.properties still mean what it means today? |
| Managed dependencies | Upgrades, downgrades, and artifacts added or removed across the BOM, split into major, minor, and patch | Which libraries under my code are moving, and by how much? |
| Extensions | Extensions added, removed, or changed status (e.g. experimental to stable) | Do all my extensions exist in the target release? |
| Java API | Public and protected classes, fields, methods, and constructors that were added or removed, deprecated, marked for removal, or whose signature, modifiers, or supertypes changed | Does the target release break or deprecate the APIs my code touches? |
The data behind all four comes from the artifacts Quarkus publishes on Maven Central. A command-line tool reads the BOMs, the config and extension metadata, and the class files of every release, keeps them as a dataset in the quarkusio/almanac repository, and a GitHub workflow adds new releases every twelve hours. The site itself never phones home — your browser computes each comparison locally.
How Do You Review Configuration Changes Between Releases?
Configuration changes are the most common source of upgrade pain, so open this section first. For every property, the Almanac shows whether it was added, removed, or changed — and "changed" is broken down into default value, type, accepted values, or the build/runtime phase the property belongs to, plus deprecation status.
A concrete example from the launch coverage: the property quarkus.hibernate-orm.database.generation, deprecated since Quarkus 3.22, no longer exists in Quarkus 4.0. If your application.properties sets it, your app will not just misbehave on 4.0 — the property is gone, and anything relying on that setting needs a deliberate replacement. That is exactly the kind of finding the config section exists to surface before you upgrade, and it is why "quarkus configuration changes between releases" is the highest-value query the Almanac answers.
Two practical habits make this section pay off. First, filter by your extensions instead of reading the whole list — a team on Hibernate ORM and RESTEasy Reactive cares about a small slice of the property universe. Second, when a property was deprecated, open its history page and find the first release carrying the deprecation mark; that tells you how long you have been on borrowed time and whether the target release finally removes it.
How Do You Check Managed Dependencies?
The dependencies section is where you learn what moved under your code. It lists every managed artifact that was upgraded, downgraded, added, or removed, separated into major, minor, and patch upgrades — so a glance tells you whether you are looking at routine maintenance or a compatibility event.
The announcement's worked example shows the granularity: from Quarkus 3.33.3 to 3.33.4, the platform BOM upgrades 68 Jackson artifacts from 2.21.6 to 2.21.7. That is a patch-level move across a lot of artifacts — low risk, but exactly the kind of thing you want on record before a security team asks. The section exists so your quarkus managed dependencies comparison is a document, not a memory.
If you manage your own BOM imports, note the coverage detail the README makes explicit: the data comes from the artifacts published on Maven Central, and release dates are the BOM upload times there — so when the Almanac says a release introduced a change, that is the moment the artifact became real, not the moment a blog post announced it.
How Do You Check Extension Compatibility?
The extensions section answers a simple, high-stakes question: does everything my project uses still exist, with the same status, in the release I want? Extensions can be added, removed, or graduate from experimental to stable, and each of those has a different implication.
The launch materials give a real example of the middle case: between the LTS releases 3.27 and 3.33, the Derby extensions were removed, while CycloneDX and Security became stable. If you are planning that LTS jump, this one section tells you to find a Derby replacement, lets you start depending on CycloneDX with confidence, and upgrades Security from a maybe to a yes. For teams doing a quarkus extension compatibility review, this section is the authoritative source — it is built from the releases themselves, not from migration notes someone may or may not have updated.
How Do You Find Java API Deprecations and Removals?
The API section compares the public and protected classes, fields, methods, and constructors in the Quarkus jars: what was added or removed, what was deprecated or marked for removal, and what changed signature, modifiers, or supertypes. This is your quarkus api deprecations check — the place to catch the removal your compiler will not warn you about until it is too late.
The announcement's worked example is worth reading slowly, because it shows how removals actually happen: the test class QuarkusUnitTest moved from the quarkus-junit5-internal artifact to quarkus-junit-internal in 3.31, was deprecated for removal in 3.35, and is gone in 4.0.0.Beta2. Three releases of warning, spread across two years, then removal. The Almanac's per-class history pages make this lifecycle visible in one place — open the history page for any class your tests touch and you can see the same arc.
One caveat belongs here because it bites people who expect a source-level diff: the API comparison reads bytecode, not source. Signatures are erased, so a change confined to generic types does not appear, and throws clauses are not read, so a change in declared exceptions does not appear either. The API surface is also the public-or-protected members of the io.quarkus jars, Quarkus internals included — so a change in an internal class shows up even though your code was never supposed to touch it. Read accordingly: absence of a change in the API section is not proof that nothing changed.
Platform BOM vs Core BOM: Which Comparison Do You Want?
This is the one setting that changes the dependency story completely. Quarkus projects come in two flavors: generated projects import the platform BOM (io.quarkus.platform:quarkus-bom), which manages the full curated dependency set, while the core BOM (io.quarkus:quarkus-bom) manages just the framework's own artifacts. The Almanac compares the platform BOMs when both releases have one — and offers a Platform BOM switch you turn off to compare the core BOMs instead.
| Platform BOM comparison (default) | Core BOM comparison (switch off) | |
|---|---|---|
| BOM compared | io.quarkus.platform:quarkus-bom | io.quarkus:quarkus-bom |
| Matches which projects | Standard generated Quarkus projects | Projects importing only the core BOM |
| What the Jackson example shows | 68 artifacts 2.21.6 to 2.21.7 | Jackson stays at 2.21.6 |
| Use it when | You built from a normal Quarkus project template | You manage BOM imports by hand and want the framework-only view |
The Jackson example from the announcement makes the point concrete: from 3.33.3 to 3.33.4, the platform BOM moves those 68 Jackson artifacts while the core BOM keeps them at 2.21.6. Read the platform comparison when your project imports the platform BOM, and you will see the dependency world your app actually lives in. Beginners who leave the switch in the wrong position end up reviewing a dependency set their project never uses — check the switch once, before you read a single dependency row. Note that platform BOMs only exist from Quarkus 2.0 onward, so very old comparisons are core-BOM by nature.
How Do You Run the Almanac CLI?
The website covers most upgrade reviews, but the dataset and the comparison logic are also available as a Java command-line tool — the same tool that builds the site's data. This is the quarkus almanac tutorial branch for people who want to script checks, archive datasets, or compare releases the site has not ingested yet.
First, the honest framing: the tool is built from source; there is no published binary. The quarkusio/almanac repository has no releases and no tags as of this writing — it is four days old. You need JDK 21 or newer and Maven 3.9 or newer (Node.js is only needed if you also want to run the site's tests). If you are new to the version-control side of this, our Git beginner guide covers cloning the repo.
mvn package # builds target/quarkus-almanac.jar from the repo sources java -jar target/quarkus-almanac.jar bom --versions 3.27,3.33 --help java -jar target/quarkus-almanac.jar bom --versions 3.27,3.33 java -jar target/quarkus-almanac.jar config --versions 3.27,3.33 java -jar target/quarkus-almanac.jar api --versions 3.27,3.33
The tool's subcommands mirror the site's sections: bom, config, and api each take a --versions pair and print the corresponding comparison. Every command also accepts --help, which is the fastest way to learn the flags. The dataset commands go deeper: dataset import pulls release data from Maven Central for chosen versions and data kinds, dataset refresh-releases updates the release list, dataset verify checks the dataset's integrity, and assemble builds the site data. A typical offline refresh looks like this:
java -jar target/quarkus-almanac.jar dataset import \ --versions 3.27,3.33 --kinds bom,config,extensions,classes,api --offline java -jar target/quarkus-almanac.jar dataset verify --offline
The automated workflow on the repository does this for you every twelve hours — adding any releases published on GitHub at least six hours ago, committing to main, and redeploying the site. Run the CLI yourself when you need a comparison the site has not computed yet, when you want the raw dataset in your own pipeline, or when you are offline and the website is not an option. If you deploy the apps you are upgrading, keep an SSH key guide handy — server deploys after a framework upgrade are exactly when key access matters.
Quarkus 3 to 4 Migration Checklist: How the Almanac Fits
Quarkus 4 is the upgrade most teams are evaluating right now, and the timing matters: 4.0.0.Beta2 is the latest pre-release as of this writing, with the final release planned for the end of November 2026 — so Quarkus 4 is not GA yet, and your review is advance planning, not emergency response. Here is a quarkus 3 to 4 migration checklist with the Almanac doing the discovery work — treat this section as your quarkus 4 upgrade guide in checklist form.
| Checklist step | What to do in the Almanac | What you are looking for |
|---|---|---|
| 1. Inventory your extensions | Compare your 3.x stream against 4.0.0.Beta2, Extensions section | Removed extensions (like Derby was, between 3.27 and 3.33) and status changes on the ones you use |
| 2. Sweep your config | Same comparison, Configuration section, filtered to your extensions | Removed or deprecated properties — e.g. quarkus.hibernate-orm.database.generation, deprecated since 3.22 and gone in 4.0 |
| 3. Review managed dependencies | Same comparison, Dependencies section, correct BOM switch | Major upgrades your libraries must be compatible with; confirm you are reading the platform BOM if that is what your project imports |
| 4. Audit your API usage | Same comparison, API section; open history pages for classes you touch | Deprecations and removals — e.g. the QuarkusUnitTest lifecycle from move (3.31) to deprecation (3.35) to removal (4.0.0.Beta2) |
| 5. Verify on the beta, upgrade on GA | Re-run the comparison against the final 4.0 when it ships | Anything that changed between the beta you tested and the GA you ship |
Two habits make this a living checklist rather than a one-off document. Run the comparison twice: once against the current beta to plan the work, and again against the GA release when it lands, because betas are moving targets. And keep the Almanac open next to your pull request — when a reviewer asks "did anything else change in that release," the per-release pages link the relevant comparisons (previous minor, previous LTS) plus the managed-artifact, config-property, and extension counts for the release, so the answer is one click away. For the review workflow itself, our GitHub beginner guide covers the PR side of landing an upgrade.
Almanac vs the Quarkus Update Tool: Which One Do You Need?
Newcomers sometimes confuse the Almanac with the Quarkus update tooling, so draw the line once: the update tooling applies changes to your project — it rewrites recipes, migrates code, and bumps versions. The Almanac shows changes between releases so you can decide what to do. They are complementary, not competitors.
Use the Almanac first, to understand the blast radius: which properties changed meaning, which dependencies moved, which extensions changed status, which APIs your code touches were deprecated. Then use the update tooling to execute the migration with that understanding in hand. The common mistake is running the updater blind and discovering the semantic changes in production — the Almanac exists precisely so the updater is never blind. In short, the quarkus update tool vs almanac question resolves to a sequence: review with the Almanac, migrate with the update tool, verify against the GA comparison when it ships.
What Are the Almanac's Documented Limits?
Every comparison tool has a boundary, and the Almanac's README states its limits plainly. Knowing them keeps you from treating a clean comparison as a guarantee.
| Limit | What it means for your review |
|---|---|
| Core extensions only | Coverage is the io.quarkus artifacts managed by quarkus-bom. Community extensions outside that set are not compared. |
| Config before 3.25 is reconstructed from bytecode | Details for older streams can differ from their documentation — treat pre-3.25 config rows as approximate. |
| Generics and throws are invisible in the API diff | Signatures are erased in bytecode and throws clauses are not read, so changes confined to generic types or declared exceptions do not appear. |
| Classes are the io.quarkus jars only | Subgroup artifacts like io.quarkus.arc classes are outside the comparison, as are shaded packages, quarkus-grpc-cli, and quarkus-bootstrap-gradle-resolver. |
| Extensions start at 0.27; platform BOMs at 2.0 | Comparisons involving the oldest releases are partial by construction. |
| Release dates are BOM upload times | "When" a release changed something means when the artifact hit Maven Central. |
None of these limits makes the Almanac unreliable for its stated job — comparing core releases on the four dimensions. They matter when you extrapolate: a community extension you depend on, a pre-3.25 config property, or a generics-only signature change all sit outside the comparison, and your review should cover those by hand. Say the boundary once, respect it always, and the tool will not surprise you.
Sources
Every fact on this page comes from a page fetched on November 2, 2026.
ADTmag, "Quarkus Almanac Gives Developers a Detailed View of Upgrade Changes," by John K. Waters (Converge360), October 30, 2026 — https://adtmag.com/articles/2026/10/30/quarkus-almanac-gives-developers-a-detailed-view-of-upgrade-changes.aspx — the announcement date and the four comparison dimensions; the quarkus.hibernate-orm.database.generation example (deprecated since 3.22, removed in 4.0); the dependency-BOM distinction; the documented limits (core-extensions-only coverage, older config reconstructed from bytecode, generics/throws invisibility).
Quarkus project announcement, "Quarkus Almanac" (October 29, 2026; official text via mirror) — https://postgoo.com/posts/6ae552432f9acdfe8b64e583?type=article — the four compared dimensions; inspiration from javaalmanac.io; home-page quick comparisons and collapsed sections; the config section's groupings and filters; the platform-vs-core BOM switch and the Jackson worked example (68 artifacts, 2.21.6 to 2.21.7, platform vs core); the Derby/CycloneDX/Security extension example between LTS 3.27 and 3.33; the API section's scope and the QuarkusUnitTest lifecycle example; the releases page and per-item history pages; the twelve-hour GitHub workflow; the site URL https://quarkus.io/almanac/.
quarkusio/almanac GitHub repository README (fetched November 2, 2026) — https://github.com/quarkusio/almanac — coverage precision (BOMs on Maven Central from 0.11.0; 0.0.1/0.1.0 had no BOM; 0.9.0 canceled); the site URL; the CLI's requirements (JDK 21+, Maven 3.9+, Node.js for site tests), build (mvn package to target/quarkus-almanac.jar), and commands (bom, config, api, dataset import/refresh-releases/verify, assemble, --help); the workflow cadence (releases at least six hours old, every twelve hours); the verbatim limitations list; the zero releases/tags state.
Quarkus blog, "Quarkus 4.0.0.Beta1 released" (October 1, 2026) — https://quarkus.io/blog/quarkus-4-0-0-beta1-released/ — the final 4.0 release planned for the end of November 2026; Maven Central listings confirming 4.0.0.Beta2 as the latest pre-release (October 29, 2026).
Frequently Asked Questions
Is the Quarkus Almanac free to use?
Yes. The site at https://quarkus.io/almanac/ is free, requires no account, and computes comparisons in your browser. The dataset and CLI come from the open quarkusio/almanac repository, and the data itself is extracted from the public Maven Central artifacts.
Do I need to install anything to use the Almanac?
No — for the website, nothing. Open https://quarkus.io/almanac/, pick two releases, and start reading. You only need an install if you want the CLI: clone the quarkusio/almanac repo, have JDK 21+ and Maven 3.9+ ready, and run mvn package. There is no published binary to download.
Which releases can the Almanac compare?
Every Quarkus release whose BOM is on Maven Central, from 0.11.0 onward, including pre-releases. Extensions comparisons start at 0.27 and platform-BOM comparisons at 2.0. Releases without a BOM (0.0.1, 0.1.0, and the canceled 0.9.0) are outside the comparison range.
Should I compare the platform BOM or the core BOM?
Match the switch to your project: if your project imports io.quarkus.platform:quarkus-bom (the standard for generated projects), keep the default platform-BOM comparison. If you import only io.quarkus:quarkus-bom by hand, turn the Platform BOM switch off. Reading the wrong one shows you a dependency world your project does not live in.
Does the Almanac replace the Quarkus update tool?
No. The Almanac reviews — it shows what changed between releases so you can plan. The update tooling migrates — it applies changes to your project. Review with the Almanac first, then migrate with the update tool, and re-run the comparison against the GA release before you ship.
