Master Spring Boot Config: Customize File Names, Paths, and Optional Locations

Environment: Spring Boot 2.4.10

When the application starts, Spring Boot automatically searches for and loads application.properties and application.yaml from the following locations (ordered by priority, lower items override higher ones):

Root of the classpath and the /config package on the classpath.

The /config subdirectory of the current working directory and its direct subdirectories.

The loading order is reversed, so later entries have higher precedence. The documents are added to the Spring Environment as PropertySources.

1. Change the configuration file name

By default Spring Boot loads files prefixed with application. You can change the name with the spring.config.name startup parameter:

java -jar myproject.jar --spring.config.name=myproject

2. Change the configuration file path

Use the spring.config.location property to specify explicit locations. It accepts a comma‑separated list of one or more locations. The optional: prefix marks a location as optional (the file may be missing).

java -jar myproject.jar --spring.config.location=optional:classpath:/default.properties,optional:classpath:/override.properties

If a location ends with a slash, it is treated as a directory. The files found there are loaded after the names generated from spring.config.name.

3. Optional locations

When a location is optional, Spring Boot will not fail if the file does not exist. You can also use spring.config.on-not-found to ignore all ConfigDataLocationNotFoundException and continue startup.

4. Wildcard locations

If a location contains a trailing *, it is treated as a wildcard. Spring Boot expands the wildcard to include direct sub‑directories. This is useful in environments like Kubernetes where multiple configuration sources may exist.

By default Spring Boot includes config/*/ in its search path, meaning every subdirectory under /config outside the jar is scanned.

5. Profile‑specific files

In addition to the generic files, Spring Boot loads profile‑specific files such as application‑prod.yml when the prod profile is active. Profile‑specific files are loaded from the same locations and always override non‑specific files. When multiple profiles are active, the later profile wins.

6. Importing additional data

The spring.config.import property can import configuration from other locations. The import is processed as soon as it is discovered and the imported documents are inserted below the declaring document.

spring:
  config:
    import:
      - optional:classpath:./config/cfg.yml

The optional prefix indicates that the imported file may be absent.

Multiple locations can be listed under a single spring.config.import key; they are processed in order, with later imports taking precedence.

7. Importing files without an extension

Some cloud platforms mount files without extensions. To import such files, hint the format by placing the extension in square brackets:

spring:
  config:
    import: "file:/etc/config/myconfig[.yaml]"

Done!