Spring Boot Profiles

@Bean
@ConditionalOnProperty(name = "shop.recommendations.enabled", havingValue = "true")
public RecommendationService recommendationService() { ... }

Use @Profile when the choice depends on where the app runs, and @ConditionalOnProperty when it depends on whether a feature is wanted, which may differ even between two production deployments.

Yes. prod, Prod and PROD are three different profiles. Activating Prod does not load application-prod.properties, and beans marked @Profile("prod") are not created.

Stick to one style for every profile name, ideally lowercase letters with hyphens, such as prod, local-docker or eu-west.

Accidentally starting production with no profile is a real risk. Two simple safeguards:

• Required placeholders: production settings such as ${DB_PASSWORD} without a default stop startup when missing.
• An explicit check at startup:

@Component
public class ProfileGuard {

    public ProfileGuard(Environment environment) {
        if (environment.getActiveProfiles().length == 0) {
            throw new IllegalStateException(
                    "No active profile set. Use SPRING_PROFILES_ACTIVE=dev|test|prod");
        }
    }
}

Combined with a clear message, this turns a silent misconfiguration into an obvious, immediate error.

Yes. Spring Boot also looks for configuration files next to the JAR, and those override the ones packaged inside it:

/opt/shop/
├── shop-service.jar
└── config/
    ├── application.properties
    └── application-prod.properties

To use another folder, point to it at startup:

java -jar shop-service.jar --spring.config.additional-location=file:/etc/shop/

This lets operations teams adjust settings for a server without rebuilding the application.

Both are loaded. If they set the same property in the same location, the .properties file wins over the .yml file. The same applies to profile files, such as application-dev.properties over application-dev.yml.

Mixing both formats in one project is confusing, so choose one format and use it everywhere.

Prefer Spring profiles. They let one JAR run in every environment. Building a separate JAR per environment with Maven profiles means production may run a binary that was never tested.

Yes. Add the exclusion to that profile’s file only:

# application-demo.properties: run the demo without any database
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

Other profiles keep the auto-configuration. This is handy for lightweight demo or documentation modes that do not need every external system.

Not within one test class. @ActiveProfiles applies to the whole class, because the Spring context is created once per configuration. Use separate test classes instead:

@SpringBootTest
@ActiveProfiles("test")
class CheckoutWithFakePaymentsTest { ... }

@SpringBootTest
@ActiveProfiles({"test", "real-payments-sandbox"})
class CheckoutWithSandboxPaymentsTest { ... }

Remember that each unique combination of profiles creates its own context, so keep the number of combinations small.

Automatically. A @ConfigurationProperties class reads its values from the combined configuration, so each environment simply gets its own values:

# application-dev.properties
shop.shipping.free-above=0

# application-prod.properties
shop.shipping.free-above=999

@ConfigurationProperties(prefix = "shop.shipping")
public record ShippingProperties(BigDecimal freeAbove) { }

The class stays the same; only the values change with the active profile.

Expose Actuator’s env endpoint during development, then look up the property:

curl http://localhost:8080/actuator/env/server.port

The response lists every source that defines the property, such as application-dev.properties, application.properties or an environment variable, and which value is actually used. This quickly explains “why is my setting ignored?” problems.

Keep this endpoint closed or secured in production, because it reveals configuration details.

Usually not. Profiles describe environments. If you create a profile for every feature, such as new-checkout or beta-search, the number of combinations grows quickly and becomes hard to reason about.

For features, use a simple property:

shop.features.new-checkout=true

Read it with @ConditionalOnProperty or @Value. For features that change at runtime or per user, a dedicated feature-flag tool is a better fit.

As few as possible. Most applications are well served by three or four:

• local or dev for developer machines.
• test for automated tests.
• prod for production, plus staging if you have it.

When you need finer pieces, such as postgres or kafka, combine them into a few groups so people still activate just one name per environment.

spring.profiles.include adds extra profiles whenever the configuration is loaded, on top of the active ones. In current Spring Boot versions it may only be set in non-profile-specific files, such as application.properties.

For most needs, profile groups are clearer: they say “when production is active, also activate these”, all in one place. Use include only for profiles that must be active in every environment.

No. Profiles are resolved once, at startup, to decide which files to read and which beans to create. After that, the running application is the same as one configured without profiles.

The settings inside a profile can of course affect performance, for example a DEBUG log level in production would slow things down, which is one more reason to check the active profile after every deployment.

Yes. @ActiveProfiles works with every Spring test, including slices:

@WebMvcTest(ProductController.class)
@ActiveProfiles("test")
class ProductControllerTest {
    // application-test.properties is loaded, and @Profile("test") beans
    // are created if they belong to the web slice
}

Remember that a slice only loads part of the application, so a @Profile("test") service is still not created in a @WebMvcTest. Provide it with @MockitoBean instead.

Use a personal profile file that is ignored by version control:

# .gitignore
src/main/resources/application-local.properties

# application-local.properties (on your machine only)
spring.datasource.url=jdbc:postgresql://localhost:5433/shop
spring.datasource.password=my-local-password

Each developer activates dev,local. Shared development settings live in the committed application-dev.properties, while personal overrides, such as a different port or password, stay on their own machine. Commit an application-local.properties.example file to show what can be set.

Yes. Besides profiles, a configuration document can activate on the detected cloud platform:

---
spring:
  config:
    activate:
      on-cloud-platform: kubernetes
management:
  endpoint:
    health:
      probes:
        enabled: true

Spring Boot detects Kubernetes from environment variables that Kubernetes sets in every container. The same approach works for other platforms, such as Cloud Foundry, without anyone choosing a profile.

Many systems do not allow dots in environment variable names, so Spring Boot uses relaxed binding: it converts SPRING_PROFILES_ACTIVE into spring.profiles.active automatically. The rule is simple: uppercase, and replace dots and hyphens with underscores.

This lets you override any setting, not just the profile, from a container or server environment.

Central configuration servers, such as Spring Cloud Config, use the same profile names. When an application named shop-service starts with the prod profile, it fetches files like:

shop-service.yml          <- shared settings for this application
shop-service-prod.yml     <- production settings for this application

So everything on this page still applies; the files simply live in a central repository instead of inside each JAR, which makes it easier to manage many services together.

Both, in layers. The Spring Framework provides the core: @Profile, the Environment API and the spring.profiles.active property.

Spring Boot adds the conveniences on top: loading application-{profile}.properties and YAML files automatically, profile groups, spring.config.activate.on-profile, <springProfile> in logging configuration, and clear startup log messages. See Spring Boot vs Spring Framework for more on how the two fit together.