Introduction

Spring Boot profiles let you switch configuration and beans based on the environment your application is running in. That is useful for things like development databases, production-only integrations, or local debugging features. The core idea is simple: keep common settings in the base config, then layer profile-specific overrides on top.

Put Shared and Environment-Specific Config in Separate Files

The most common pattern is:

• 'application.yml for shared defaults'
• 'application-dev.yml for development overrides'
• 'application-prod.yml for production overrides'

Example base configuration:

1server:
2  port: 8080
3
4spring:
5  datasource:
6    username: app

Example development override in application-dev.yml:

1spring:
2  datasource:
3    url: jdbc:postgresql://localhost:5432/app_dev
4    password: devpass

Example production override in application-prod.yml:

1spring:
2  datasource:
3    url: jdbc:postgresql://db.internal:5432/app_prod
4    password: prodpass

When dev is active, Boot loads the base file and then overrides matching values with those from application-dev.yml.

Activate Profiles

The current profile can be activated in several ways.

At the command line:

java -jar app.jar --spring.profiles.active=dev

With an environment variable:

export SPRING_PROFILES_ACTIVE=prod

In tests:

1import org.springframework.test.context.ActiveProfiles;
2
3@ActiveProfiles("test")
4class UserServiceTest {
5}

You can also set spring.profiles.active in configuration, but that is usually best reserved for local defaults rather than deployment-controlled environments.

Load Beans Only for Certain Profiles

Profiles are not just for properties. They also control bean registration with @Profile.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.context.annotation.Profile;
4
5@Configuration
6public class StorageConfig {
7
8    @Bean
9    @Profile("dev")
10    StorageService localStorageService() {
11        return new LocalStorageService();
12    }
13
14    @Bean
15    @Profile("prod")
16    StorageService s3StorageService() {
17        return new S3StorageService();
18    }
19}

That keeps environment-specific wiring out of your business logic.

Use spring.config.activate.on-profile for YAML Sections

Instead of separate files, you can also put multiple YAML documents in one file and activate sections by profile.

1server:
2  port: 8080
3
4---
5spring:
6  config:
7    activate:
8      on-profile: dev
9  datasource:
10    url: jdbc:postgresql://localhost:5432/app_dev
11
12---
13spring:
14  config:
15    activate:
16      on-profile: prod
17  datasource:
18    url: jdbc:postgresql://db.internal:5432/app_prod

This is the current style for profile-specific YAML documents. It is clearer than older profile markers and matches modern Boot configuration handling.

Use Profile Groups for Bundles of Behavior

If your application has related settings that should always travel together, profile groups can help.

spring.profiles.group.staging=prod,metrics

Now activating staging also activates prod and metrics. This can reduce duplication when environments share most behavior with just a few extra features layered on.

Profiles also interact with normal property precedence. Command-line arguments, environment variables, and external config can still override values inside profile files. That is useful in deployments because you can keep environment shape in profiles while leaving last-mile differences to runtime configuration.

Common Pitfalls

The first mistake is putting every environment difference into profiles, including secrets that should really come from external secret management or environment variables.

Another issue is activating a profile from inside a profile-specific document. That creates confusing configuration cycles and should be avoided.

Some developers also overuse @Profile for business decisions that belong in normal application configuration. Profiles are best for environment shape, not for everyday runtime branching.

Finally, remember that multiple profiles can be active at once. If two active profiles define the same property, override order matters, so keep the configuration model deliberate rather than accidental.

Summary

• Spring Boot profiles let you layer environment-specific configuration and beans on top of shared defaults.
• The common pattern is application.yml plus files like application-dev.yml and application-prod.yml.
• Activate profiles with CLI args, environment variables, or @ActiveProfiles in tests.
• Use @Profile for environment-specific bean registration.
• Prefer spring.config.activate.on-profile for profile-specific YAML sections in current Boot configuration.