Quarkus Configuration Profiles for Dev Test and Prod
Configure a Quarkus application with profiles: the built in dev, test and prod, the percent prefix syntax, custom profiles, environment variables and secrets.

Quarkus reads one file, application.properties, and switches values by profile, so the same build runs with a debug logger on a laptop, a random port in tests and a real database in production. The mechanism is small and a few details decide whether it behaves: the three built-in profiles, how a custom one is selected, the precedence of the sources, and the difference between properties read at build time and those read when the application starts. This guide covers each on Quarkus 3 with JDK 25. The Spring-flavoured comparison is in Quarkus for Spring developers.
The three built-in profiles
| Profile | Active when |
|---|---|
dev | quarkus dev or ./mvnw quarkus:dev |
test | Running @QuarkusTest tests |
prod | Running the packaged application |
greeting.message=Hello
quarkus.http.port=8080
%dev.greeting.message=Hello from dev
%dev.quarkus.log.console.level=DEBUG
%test.quarkus.http.test-port=0
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/shop
%prod.quarkus.log.level=INFOA key with a %dev. prefix replaces the plain key while the profile is dev, and is ignored otherwise. A key without a prefix is the default for every profile. The profile is chosen for you: the dev command sets dev, the test runner sets test and a packaged jar runs as prod. Dev mode and Dev Services rely on the dev and test profiles to supply a database without any URL in the file, which is why leaving the datasource URL unset outside %prod is deliberate.
Custom profiles
java -Dquarkus.profile=staging -jar target/quarkus-app/quarkus-run.jar%staging.quarkus.datasource.jdbc.url=jdbc:postgresql://staging-db:5432/shopYou can also set QUARKUS_PROFILE=staging in the environment, which suits containers. A profile name can be a list such as dev,local, with the later ones winning when both define a key. Keep the number of custom profiles small: every profile is another combination to test, and a "staging" that differs from "prod" in many keys stops being a useful rehearsal.
Separate files
Per-profile files such as application-staging.properties are loaded as well, which keeps long overrides apart from the main file. A file placed in config/application.properties next to the packaged jar overrides the packaged values without a rebuild, a handy way to supply per-environment settings with a mounted file. YAML works with the quarkus-config-yaml extension, using the same keys.
Environment variables
At deployment time, environment variables take precedence over the file:
QUARKUS_HTTP_PORT=9090 \
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://db:5432/shop \
GREETING_MESSAGE=Bonjour \
java -jar target/quarkus-app/quarkus-run.jarThe rule is uppercase letters, with dots and dashes replaced by underscores. That suits containers and Kubernetes, as set out in setting JVM options in Docker. The precedence, from highest to lowest, is system properties, environment variables, the config/application.properties file and then the packaged file, so a value set higher always wins, and the reference page lists the full order.
Build time versus runtime
Some properties are read at build time and baked into the application: the datasource kind, which extensions are enabled and many quarkus.* build switches. Changing them with an environment variable at run time has no effect, and Quarkus warns about the mismatch at start-up, with a line saying that a build-time property was changed at run time. The documentation marks those properties with a lock icon. This is a direct consequence of build-time processing, which is also what makes start-up fast. When a setting seems to be ignored, check this first.
Injecting values
@ApplicationScoped
class Greeter {
@ConfigProperty(name = "greeting.message", defaultValue = "Hi")
String message;
}For groups of values, prefer a @ConfigMapping interface, which binds a prefix to a typed object and validates it at start-up, so a missing required key stops the application with a message naming the key. That is better than a null found later in a request. Give every property a sensible default only if the application can really run without it; a default that hides a missing production setting is worse than a failure.
Secrets
Do not commit a production password in %prod. lines. Provide it with an environment variable, a Kubernetes secret mounted as a file, or the Vault extension. The properties file should hold structure, and the deployment should hold secrets. If a secret has been committed once, rotate it, because removing it from the file does not remove it from history.
Testing configuration
A @QuarkusTest runs with the test profile, so assertions about production values need another route. Write a plain unit test for the @ConfigMapping interface using SmallRyeConfigBuilder with explicit values, and test the validation rules there. For the prod profile itself, a smoke test in the pipeline that starts the packaged jar with the production profile and calls the health endpoint catches missing keys before a deployment.
Profile-specific beans and extensions
Profiles also switch code. @IfBuildProfile("dev") includes a bean only in dev builds, and @UnlessBuildProfile("prod") excludes it from production, which is how a fake payment gateway stays out of the shipped application. @IfBuildProperty does the same for a property value. These conditions are evaluated at build time, so they remove the bean from the packaged application entirely, unlike a runtime if. Use them for test doubles, debug endpoints and developer tools, and check that the production build does not contain them.
Checking what is active
Log the active profile at start-up, and expose it in your health or info output, so an operator can confirm that a pod runs with prod. The Dev UI's configuration page lists every property with the source that supplied it, which answers "why is this value what it is" quickly. In a deployed application, run with -Dquarkus.log.category."io.quarkus.config".level=DEBUG to see which sources are consulted when a value is surprising.
A short checklist for a new service
Put the defaults a developer needs in the plain keys, put the production hostnames in %prod, leave secrets out of the file and run the packaged jar once with the production profile before the first deployment.
Profiles in the pipeline
Match pipeline stages to profiles. Unit tests run with the test profile, integration tests start a container with dev services, and the smoke test starts the packaged jar with the production profile against a staging database.
When profiles are the wrong tool
If you need to change behaviour without restarting, use a feature-flag service, because profile selection happens once at start-up. Do not use profiles to hide business differences between customers; that belongs in data. The references are the Quarkus configuration reference and its section on profiles, which lists the precedence order.


