Complete Guide to Spring Boot Profiles

What profiles are for

Spring Boot profiles separate configuration for different environments such as local development, testing, staging, and production. Shared values belong in application.yml or application.properties, while environment-specific values belong in application-dev.yml, application-test.yml, or application-prod.yml.

The goal is not to create more files. It is to reduce cross-environment pollution. Development can use local databases and verbose logs, while production should use controlled datasource settings, conservative logging, and explicit endpoint exposure.

spring:
  profiles:
    active: dev

# application-dev.yml
server:
  port: 8081
logging:
  level:
    root: DEBUG

Activation order and override behavior

When a setting does not take effect, the activation source is often missed. Profiles can be activated by configuration files, command-line arguments, environment variables, or deployment platforms. Later or higher-priority sources may override what you see in the file.

When debugging, print active profiles first and then confirm the final value of the same key across base and profile files. Do not infer runtime configuration from a single file.

• Startup logs usually show active profiles
• Command-line arguments can override configured active profiles
• Environment variables may come from CI/CD or container platforms
• The same key in a profile file overrides the base file

Team collaboration advice

Do not commit personal local settings into shared profiles. Provide an application-local.yml example if needed, but keep real passwords, private URLs, and personal ports in local uncommitted files or environment variables.

When reviewing production profile changes, focus on datasource, logging, management endpoints, and security-related settings. Mistakes there usually have a larger impact than ordinary feature flags.

Choose one explicit activation entry point

A developer can set SPRING_PROFILES_ACTIVE=dev in an IntelliJ IDEA Run Configuration, while containers, launch scripts, or the deployment platform inject prod. This avoids editing and committing application.yml whenever the environment changes.

spring.profiles.active and spring.profiles.default are only valid in non-profile-specific documents. They cannot be placed in application-prod.yml or in a document activated with spring.config.activate.on-profile. Move activation back to base configuration or the launch environment instead of trying to work around that restriction with file order.

# IntelliJ IDEA environment variable
SPRING_PROFILES_ACTIVE=dev

# command line
java -jar app.jar --spring.profiles.active=prod

Use profile groups for composed environments

When production needs several focused profiles such as proddb, prodmq, and observability, define a profile group. The caller activates production while the base configuration owns the exact composition, avoiding repeated profile lists in every deployment script.

group, include, and active values still follow PropertySource precedence. After changing a group, confirm the active profiles in startup logs and verify that datasource, messaging, and monitoring settings came from the expected files.

spring:
  profiles:
    group:
      production:
        - proddb
        - prodmq
        - observability

Troubleshooting references and related guides

Use a fixed sequence: identify the launch entry point, read active profiles, search duplicate keys, inspect external configuration locations, and finally verify runtime values. Spring Boot's Profiles reference documents active, default, include, and group restrictions; the full precedence order is maintained in Externalized Configuration.

• Spring Boot: Profiles
• Spring Boot: Externalized Configuration

Related guides

• Common Spring Boot application.yml Mistakes
• Spring Boot Datasource Configuration Completion and Validation