The English version of is the official project site. Translated sites are community supported on a best-effort basis.

Configuration Reference Guide

The content of this guide has been revised and split into additional topics. Please check the Additional Information section.

In this reference guide we’re going to describe various aspects of Quarkus configuration. A Quarkus application and Quarkus itself (core and extensions) are both configured via the same mechanism that leverages the SmallRye Config API an implementation of the MicroProfile Config specification.

If you’re looking for information how to make a Quarkus extension configurable then see the Writing Your Own Extension guide.

1. Config Sources

By default, Quarkus reads configuration properties from multiple sources (by descending ordinal):

  1. (400) System properties

  2. (300) Environment variables

  3. (295) .env file in the current working directory

  4. (260) Quarkus Application configuration file in $PWD/config/

  5. (250) Quarkus Application configuration file in classpath

  6. (100) MicroProfile Config configuration file META-INF/ in classpath

The final configuration is the aggregation of the properties defined by all these sources. A configuration property lookup starts by the highest ordinal configuration source available and works it way down to other sources until a match is found. This means that any configuration property may override a value just by setting a different value in a higher ordinal config source. For example, a property configured using an environment property overrides the value provided using the file.

config sources

1.1. System properties

System properties can be handed to the application through the -D flag during startup. The following examples assign the value youshallnotpass to the attribute quarkus.datasource.password.

  • For Quarkus dev mode: ./mvnw quarkus:dev -Dquarkus.datasource.password=youshallnotpass

  • For a runner jar: java -Dquarkus.datasource.password=youshallnotpass -jar target/quarkus-app/quarkus-run.jar

  • For a native executable: ./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass

1.2. Environment variables

  • For a runner jar: export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/quarkus-app/quarkus-run.jar

  • For a native executable: export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner

Environment variables names follow the conversion rules specified by MicroProfile Config.

Config searches three environment variables for a given property name (e.g. foo.BAR.baz):

  • foo.BAR.baz - Exact match

  • foo_BAR_baz - Replace each character that is neither alphanumeric nor _ with _

  • FOO_BAR_BAZ - Replace each character that is neither alphanumeric nor _ with _; then convert the name to upper case

SmallRye Config specifies additional conversion rules.

  • A property with double quotes foo."bar".baz, replace each character that is neither alphanumeric nor _ with _: FOO__BAR__BAZ

  • A property with dashes, replace each character that is neither alphanumeric nor _ with _: FOO_BAR_BAZ

  • An indexed property[0] or[0].baz, replace each character that is neither alphanumeric nor _ with _: FOO_BAR_0_ or FOO_BAR_0__BAZ

In some situations, looking up the exact property name is impossible. For instance, when looking up a configuration that is part of a Map, and the property name contains a dynamic segment (the Map key). In this case, Quarkus relies upon each source’s list of property names. These must be converted back to their most likely dotted format for Environment Variables.

By default, the underscore _ of an Environment Variable name always maps to a dot .. If the property name contains a dash or some other special character, that property name can be specified in another Config Source, with the expected dotted format. It will provide additional information to perform a two-way conversion and match the property names.

To correctly lookup Map properties where FOO_BAR_BAZ is the property name and BAR_BAZ is the key, add in a source with an ordinal lower than the EnvConfigSource (300).

1.3. .env file in the current working directory

1 The name QUARKUS_DATASOURCE_PASSWORD the same conversion rules used for Environment variables.

For dev mode, this file can be placed in the root of the project, but it is advised to not check it in to version control.

Environment variables in the .env file are not available via the System.getenv(String) API.

1.4. Quarkus Application configuration file

The Quarkus Application configuration file is loaded from the classpath resources, for instance src/main/resources/, src/test/resources/ or from a jar dependency that contains an entry. Each found is treated as a separate ConfigSource and follow the same rules as every other source (override per property). Additionally, the configuration file may also reside in $PWD/config/ The loading starts from the config folder and then classpath order ( files in the application sources will have priority on the classloader loading order).
greeting.message=hello (1)
quarkus.http.port=9090 (2)
1 This is a user-defined configuration property.
2 This is a configuration property consumed by the quarkus-vertx-http extension.
The config/ is also available in dev mode. The file needs to be placed inside the build tool output directory (target for Maven and build/classes/java/main for Gradle). Keep in mind however that any cleaning operation from the build tool like mvn clean or gradle clean will remove the config directory as well.

1.5. MicroProfile Config configuration file

The MicroProfile Config configuration file in src/main/resources/META-INF/
greeting.message=hello (1)
quarkus.http.port=9090 (2)
1 This is a user-defined configuration property.
2 This is a configuration property consumed by the quarkus-vertx-http extension.
It works in the exact same way as Quarkus Application configuration file Recommendation is to use Quarkus

1.6. Additional Config Sources

Quarkus provides additional extensions which cover other configuration formats and stores:

It is also possible to create a Custom Config Source.

2. Inject

Quarkus uses MicroProfile Config annotations to inject the configuration properties in the application.

@ConfigProperty(name = "greeting.message") (1)
String message;
1 You can use @Inject @ConfigProperty or just @ConfigProperty. The @Inject annotation is not necessary for members annotated with @ConfigProperty.
If the application attempts to inject a configuration property that is not set, an error is thrown.
@ConfigProperty(name = "greeting.message") (1)
String message;

@ConfigProperty(name = "greeting.suffix", defaultValue="!") (2)
String suffix;

@ConfigProperty(name = "")
Optional<String> name; (3)
1 If you do not provide a value for this property, the application startup fails with jakarta.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message.
2 The default value is injected if the configuration does not provide a value for greeting.suffix.
3 This property is optional - an empty Optional is injected if the configuration does not provide a value for
Use Config Mappings to group similar configuration properties.

2.1. Default Values

If a property is associated with a default value (by way of the defaultValue attribute), and no configuration value is supplied for the property, then rather than throwing a jakarta.enterprise.inject.spi.DeploymentException, the default value will be used. The defaultValue value is expressed as a String, and uses the same conversion mechanism used to process configuration values. Several Built-in Converters already exist for primitives, boxed primitives, and other classes; for example:

  • Primitives: boolean, byte, short, etc.

  • Boxed primitives: java.lang.Boolean, java.lang.Byte, java.lang.Short, etc.

  • Optional containers: java.util.Optional, java.util.OptionalInt, java.util.OptionalLong, and java.util.OptionalDouble

  • Java enum types

  • JSR 310 java.time.Duration

  • JDK networking,, etc.

As you might expect, these converters are org.eclipse.microprofile.config.spi.Converter implementations. Therefore, these converters comply with the Microprofile or custom implementation providers expression rules like:

  • Boolean values will be true in cases "true", "1", "YES", "Y" "ON". Otherwise, value will be interpreted as false

  • For float and double values the fractional digits must be separated by a dot .

Note that when a combination of Optional* types and the defaultValue attribute are used, the defined defaultValue will still be used and if no value is given for the property, the Optional* will be present and populated with the converted default value. However, when the property is explicitly empty, the default value is not used and the Optional will be empty. Consider this example:

# missing value, optional property =

In this case, since was configured to be Optional* up above, the corresponding property value will be an empty Optional and execution will continue normally. This would be the case even if there was a default value configured: the default value is not used if the property is explicitly cleared in the configuration.

On the other hand, this example:

# missing value, non-optional
greeting.suffix =

will result in a java.util.NoSuchElementException: SRCFG02004: Required property greeting.message not found on startup and the default value will not be assigned.

Below is an example of a Quarkus-supplied converter:

@ConfigProperty(name = "server.address", defaultValue = "")
InetAddress serverAddress;

3. Programmatically access

The org.eclipse.microprofile.config.ConfigProvider.getConfig() API allows to access the Config API programmatically. This API is mostly useful in situations where CDI injection is not available.

String databaseName = ConfigProvider.getConfig().getValue("", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("", String.class);
Do not use System.getProperty(String) or System.getEnv(String) to retrieve configuration values. These APIs are not configuration aware and do not support the features described in this guide.

4. Profiles

We often need to configure differently our application depending on the target environment. For example, the local development environment may be different from the production environment.

Configuration Profiles allow for multiple configurations in the same file or separate files and select between them via a profile name.

4.1. Profile in the property name

To be able to set properties with the same name, each property needs to be prefixed with a percentage sign % followed by the profile name and a dot . in the syntax %{profile-name}

The Quarkus HTTP port will be 9090. If the dev profile is active it will be 8181.

Profiles in the .env file follow the syntax _{PROFILE}_CONFIG_KEY=value:


If a profile does not define a value for a specific attribute, the default (no profile) value is used:

With the dev profile enabled, the property bar has the value hallo, but the property baz has the value bonjour. If the prod profile is enabled, bar has the value hello (as there is no specific value for the prod profile), and baz the value bonjour.

4.2. Default Profiles

By default, Quarkus provides three profiles, that activate automatically in certain conditions:

  • dev - Activated when in development mode (i.e. quarkus:dev)

  • test - Activated when running tests

  • prod - The default profile when not running in development or test mode

4.3. Custom Profiles

It is also possible to create additional profiles and activate them with the quarkus.profile configuration property. A single config property with the new profile name is the only requirement:

Setting quarkus.profile to staging will activate the staging profile.

The io.smallrye.config.SmallRyeConfig#getProfiles API provides a way to retrieve the active profiles programmatically.

4.4. Profile aware files

In this case, properties for a specific profile may reside in an application-{profile}.properties named file. The previous example may be expressed as:

In this style, the configuration names in the profile aware file do not need to be prefixed with the profile name.

Properties in the profile aware file have priority over profile aware properties defined in the main file.

The profile aware file must be present in the exact same location as the main file.

4.5. Parent Profile

A Parent Profile adds one level of hierarchy to the current profile. The configuration quarkus.config.profile.parent accepts a single profile name.

When the Parent Profile is active, if a property cannot be found in the current active Profile, the config lookup fallbacks to the Parent Profile. Consider:





  • The active profile is dev

  • The parent profile is common

  • quarkus.http.port is 9090

  • quarkus.http.ssl-port is 9443

Do not use Profile aware files to set quarkus.config.profile.parent. This will not work because the profile is required in advance to load the profile aware files.

4.6. Multiple Profiles

Multiple Profiles may be active at the same time. The configuration quarkus.profile accepts a comma-separated list of profile names: quarkus.profile=common,dev. Both common and dev are separate profiles.

When multiple profiles are active, the rules for profile configuration are the same. If two profiles define the same configuration, then the last listed profile has priority. Consider:




  • common.prop value is common

  • dev.prop value is dev

  • my.prop value is 5678

  • test.prop does not have a value

It is also possible to define multiple profile properties, with a comma-separated list of profile names. If the same property name exists in multiple profile properties then, the property name with the most specific profile wins:




  • my.prop value is 5678.

  • another.prop value is 1234.

4.7. Default Runtime Profile

The default Quarkus runtime profile is set to the profile used to build the application:

./mvnw package -Pnative -Dquarkus.profile=prod-aws
./target/my-app-1.0-runner (1)
1 The command will run with the prod-aws profile. This can be overridden using the quarkus.profile configuration.

5. Property Expressions

Quarkus provides property expressions expansion on configuration values. An expression string is a mix of plain strings and expression segments, which are wrapped by the sequence ${ …​ }.

These expressions are resolved when the property is read. So if the configuration property is build time the property expression will be resolved at build time. If the configuration property is overridable at runtime it will be resolved at runtime.


The resolved value of the callable.url property is

Another example would be defining different database servers by profile:

can be simplified to:


Additionally, the Expression Expansion engine supports the following segments:

  • ${expression:value} - Provides a default value after the : if the expansion doesn’t find a value.

  • ${my.prop${compose}} - Composed expressions. Inner expressions are resolved first.

  • ${my.prop}${my.prop} - Multiple expressions.

If an expression cannot be expanded and no default is supplied a NoSuchElementException is thrown.

Expressions lookups are performed in all config sources. The expression values and expansion values may reside in different config sources.

5.1. With Environment Variables

Property Expressions also work with Environment Variables.${HOST:${}}

This will expand the HOST environment variable and use the value of the property as the default value if HOST is not set.

6. Secret Keys Expressions

A secret configuration may be expressed as ${handler::value}, where the handler is the name of a io.smallrye.config.SecretKeysHandler to decode or decrypt the value. Consider:

A lookup to my.secret will use the SecretKeysHandler name aes-gcm-nopadding to decode the value DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg.

For more information, please check SmallRye Config Secret Keys documentation.

7. Accessing a generating UUID

The default config source from Quarkus provides a random UUID value. It generates the UUID at startup time. So, the value changes between startups, including reloads in dev mode.

You can access the generated value using the quarkus.uuid property. Use expressions to access it: ${quarkus.uuid}. For example, it can be useful to configure a Kafka client with a unique consumer group:${quarkus.uuid}

8. Clearing properties

Run time properties which are optional, and which have had values set at build time or which have a default value, may be explicitly cleared by assigning an empty string to the property. Note that this will only affect runtime properties, and will only work with properties whose values are not required.

A lookup to with will throw an Exception, because the system property cleared the value.

9. Indexed Properties

A config value which contains unescaped commas may be converted to Collection. This works for simple cases, but it becomes cumbersome and limited for more advanced cases.

Indexed Properties provide a way to use indexes in config property names to map specific elements in a Collection type. Since the indexed element is part of the property name and not contained in the value, this can also be used to map complex object types as Collection elements. Consider:


The indexed property syntax uses the property name and square brackets `[ ] with an index in between.

A call to Config#getValues("my.collection", String.class), will automatically create and convert a List<String> that contains the values dog, cat and turtle. A call to Config#getValues("my.indexed.collection", String.class) returns the exact same result. If the same property name exists in both forms (regular and indexed), the regular value has priority.

The indexed property is sorted by their index before being added to the target Collection. Any gaps contained in the indexes do not resolve to the target Collection, which means that the Collection result will store all values without any gaps.

10. Configuring Quarkus

Quarkus itself is configured via the same mechanism as your application. Quarkus reserves the quarkus. namespace for its own configuration. For example to configure the HTTP server port you can set quarkus.http.port in All the Quarkus configuration properties are documented and searchable.

As mentioned above, properties prefixed with quarkus. are effectively reserved for configuring Quarkus itself and its extensions. Therefore, the quarkus. prefix should never be used for application specific properties.

10.1. Build Time configuration

Some Quarkus configurations only take effect during build time, meaning is not possible to change them at runtime. These configurations are still available at runtime but as read-only and have no effect in Quarkus behaviour. A change to any of these configurations requires a rebuild of the application itself to reflect changes of such properties.

The properties fixed at build time are marked with a lock icon () in the list of all configuration options.

However, some extensions do define properties overridable at runtime. A simple example is the database URL, username and password which is only known specifically in your target environment, so they can be set and influence the application behaviour at runtime.

11. Change build time properties after your application has been published

If you are in the rare situation that you need to change the build time configuration after your application is built, then check out how re-augmentation can be used to rebuild the augmentation output for a different build time configuration.

13. 配置参考

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property



Profile that will be active when Quarkus launches.

Environment variable: QUARKUS_PROFILE



Accepts a single configuration profile name. If a configuration property cannot be found in the current active profile, the config performs the same lookup in the profile set by this configuration.



Additional config locations to be loaded with the Config. The configuration support multiple locations separated by a comma and each must represent a valid

Environment variable: QUARKUS_CONFIG_LOCATIONS

list of URI

A property that allows accessing a generated UUID. It generates that UUID at startup time. So it changes between two starts including in dev mode. Access this generated UUID using expressions: ${quarkus.uuid}.

Environment variable: QUARKUS_UUID