Spring.profiles.active in Spring Boot: complete guide with examples

spring.profiles.active is a Spring Boot property that tells the framework which configuration profile to load at startup. Set it once, and Spring automatically picks the right application-{profile}.yml, registers the right beans, and skips everything else. The result: one codebase, zero environment-specific hacks, clean deployments to dev, staging, and production.

The most common place to set it is application.properties:

spring.profiles.active=development

Or activate it at runtime without touching any file:

java -jar myapp.jar --spring.profiles.active=production

Understanding Spring profiles: core concepts and benefits

A Spring profile is a named set of bean definitions and configuration properties that activates together. When you mark a bean or configuration class with @Profile("production"), Spring only registers it when that profile is active. Everything else is ignored.

@Configuration
@Profile("development")
public class DevMailConfig {
    @Bean
    public JavaMailSender mailSender() {
        // Points to a local MailHog instance, never sends real email
        ...
    }
}

By default, Spring Boot validates profile names. Current documentation allows profile names to contain letters, numbers, and these characters: -, _, ., +, and @. A profile name must start and end with a letter or number. This is stricter than “any arbitrary string”, and it helps avoid parsing problems.

The practical payoff is obvious: a developer can run the app locally with lightweight infrastructure, while the production container injects hardened configuration through the active profile. Same jar, completely different runtime behavior.

The spring.profiles.active property: detailed explanation

The spring.profiles.active property accepts a comma-separated list of profile names. Spring resolves it early in the startup sequence, before bean registration begins, so profile-based bean loading, configuration file selection, and auto-configuration all happen with the final active profile list already known.

“You can use a spring.profiles.active Environment property to specify which profiles are active.”
— Spring Boot Documentation
Source link

# ✅ valid: non-profile-specific document
spring:
  profiles:
    active: production

---
# ❌ invalid: profile-specific document must not set spring.profiles.active
spring:
  config:
    activate:
      on-profile: production
  profiles:
    active: metrics

Methods for setting active profiles

Spring supports several ways to activate profiles. Each has its own place depending on whether you are running locally, inside a container, or through a CI/CD pipeline.

Where to set spring.profiles.active in real projects

Command line activation

The command line gives you the highest precedence and zero file changes. Two syntaxes work:

# JVM system property
java -Dspring.profiles.active=dev,hsqldb -jar myapplication.jar

# Spring Boot argument style
java -jar myapplication.jar --spring.profiles.active=production,mysql

Both are equivalent in effect. The Spring Boot argument style is slightly more natural in Boot-only applications, and it works especially well for one-off debugging and local testing.

Environment variables and system properties

The environment variable SPRING_PROFILES_ACTIVE is the standard way to inject profiles in containers and CI pipelines. Spring Boot maps it automatically through relaxed binding.

# Unix/Linux/macOS
export SPRING_PROFILES_ACTIVE=production,redis
java -jar myapplication.jar

# Windows Command Prompt
set SPRING_PROFILES_ACTIVE=production,redis
java -jar myapplication.jar

# Windows PowerShell
$env:SPRING_PROFILES_ACTIVE="production,redis"
java -jar myapplication.jar

In Docker Compose, pass it directly in the service definition:

services:
  app:
    image: myapp:latest
    environment:
      - SPRING_PROFILES_ACTIVE=production,redis
    ports:
      - "8080:8080"

In Kubernetes, inject it in the pod spec:

env:
  - name: SPRING_PROFILES_ACTIVE
    value: "production,redis"

System properties are an alternative when environment variables are restricted:

System.setProperty("spring.profiles.active", "development,h2");

Programmatic activation

For cases where the profile depends on runtime logic, activate it before the application context starts:

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(Application.class);
        app.setAdditionalProfiles(determineActiveProfile());
        app.run(args);
    }

    private static String determineActiveProfile() {
        return System.getProperty("deployment.environment", "development");
    }
}

setAdditionalProfiles() adds profiles to the application before startup rather than replacing every other possible source. Use it when your application needs to activate supporting profiles programmatically, not when you want to override external configuration supplied by operations or CI/CD.

For tests, prefer @ActiveProfiles instead of setting system properties manually. It is cleaner and resets automatically with the test context.

Configuration file approaches

Setting the profile in a config file provides a reliable default. This is ideal for establishing a safe local-development baseline so the app starts without any external arguments.

# application.properties
spring.profiles.active=development

# application.yml
spring:
  profiles:
    active: development

Keep this value set to your safe local profile in version control. Override it via environment variable or command line in automated environments.

Profile activation priority

When the same property is set in multiple places, Spring applies a strict precedence order. The highest-precedence source wins completely.

A common debugging trap is seeing an unexpected profile even though the properties file says something else. In practice, that usually means an environment variable or CLI argument already overrode it.

Using spring.profiles.include

Sometimes you do not want to replace the active profile list — you want to add profiles on top of it. That is what spring.profiles.include is for.

spring:
  profiles:
    include:
      - common
      - local

With this setup, common and local are added before the explicitly active profiles. This is useful for shared infrastructure profiles such as common logging, shared metrics, or local development support.

Profile-specific configuration files

Spring Boot automatically loads application-{profile}.properties or application-{profile}.yml when a profile is active. Profile-specific files are loaded after the base config and override matching keys.

src/main/resources/
├── application.yml
├── application-development.yml
├── application-testing.yml
├── application-staging.yml
└── application-production.yml

Keep the base file lean. Only properties that are truly identical across all environments belong there.

Multi-document YAML files

Instead of multiple files, you can consolidate profile-specific configuration into a single application.yml using YAML document separators.

# Applies to all profiles
server:
  port: 8080
logging:
  level:
    root: INFO

---
spring:
  config:
    activate:
      on-profile: development
datasource:
  url: jdbc:h2:mem:devdb
  username: dev
  password: dev
logging:
  level:
    com.example: DEBUG

---
spring:
  config:
    activate:
      on-profile: production
datasource:
  url: jdbc:mysql://prod-db:3306/proddb
  username: ${DB_USERNAME}
  password: ${DB_PASSWORD}
logging:
  level:
    com.example: WARN

In Spring Boot 2.4+, use spring.config.activate.on-profile for YAML document activation. It is the modern and recommended form.

Real-world implementation examples

The most common real-world profile scenarios are database configuration, feature toggles, and logging behavior.

Database configuration:

@Configuration
@Profile("development")
public class DevelopmentDatabaseConfig {

    @Bean
    @Primary
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
            .setType(EmbeddedDatabaseType.H2)
            .addScript("schema.sql")
            .addScript("test-data.sql")
            .build();
    }
}

@Configuration
@Profile("production")
public class ProductionDatabaseConfig {

    @Bean
    @Primary
    public DataSource dataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:mysql://prod-db:3306/proddb");
        config.setUsername("${DB_USERNAME}");
        config.setPassword("${DB_PASSWORD}");
        config.setMaximumPoolSize(20);
        return new HikariDataSource(config);
    }
}

Feature toggles:

@Controller
@Profile("feature-new-ui")
public class NewDashboardController {

    @GetMapping("/dashboard")
    public String newDashboard(Model model) {
        return "new-dashboard";
    }
}

@Controller
@Profile("!feature-new-ui")
public class LegacyDashboardController {

    @GetMapping("/dashboard")
    public String legacyDashboard(Model model) {
        return "legacy-dashboard";
    }
}

Logging:

# application-development.yml
logging:
  level:
    com.example: DEBUG
    org.springframework.web: DEBUG

# application-production.yml
logging:
  level:
    com.example: WARN
    root: ERROR

Default profile and its purpose

The default profile is a safety net. Spring activates it automatically when no other profiles are set.

@Configuration
@Profile("default")
public class DefaultConfiguration {

    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
            .setType(EmbeddedDatabaseType.H2)
            .build();
    }

    @Bean
    public CacheManager cacheManager() {
        return new ConcurrentMapCacheManager();
    }
}

You can also rename the default profile using spring.profiles.default:

spring.profiles.default=local-development

In practice, the default profile should represent “what a developer gets on first clone” — safe local dependencies, no production secrets, no real external side effects.

Spring Boot profile integration

Spring Boot adds a few important features on top of base Spring profile support, especially for configuration files and deployment workflows.

Maven integration:

<profiles>
    <profile>
        <id>development</id>
        <properties>
            <spring.profiles.active>dev,h2</spring.profiles.active>
        </properties>
    </profile>
    <profile>
        <id>production</id>
        <properties>
            <spring.profiles.active>prod,mysql</spring.profiles.active>
        </properties>
    </profile>
</profiles>

Gradle integration:

bootRun {
    args = ["--spring.profiles.active=${project.findProperty('profile') ?: 'development'}"]
}
// Run with: ./gradlew bootRun -Pprofile=production

Profile groups in Spring Boot

Profile groups let you activate multiple profiles with one logical name. This is cleaner than forcing operators to remember long comma-separated lists.

spring:
  profiles:
    group:
      production: "proddb,prodcache,prodlogging"
      development: "devdb,devcache,devlogging,debug"
      testing: "testdb,testcache,mockedservices"

Groups can also be composed for larger setups:

spring:
  profiles:
    group:
      database-dev: "h2,flyway"
      database-prod: "mysql,flyway"
      cache-dev: "simple-cache"
      cache-prod: "redis,redis-cluster"

      full-dev: "database-dev,cache-dev,debug"
      full-prod: "database-prod,cache-prod,monitoring"

Profile groups are especially useful when environments activate multiple infrastructure capabilities together and you want a single, memorable top-level profile such as production.

Best practices and common pitfalls

Debugging and troubleshooting profile issues

Enable useful debug logging:

logging.level.org.springframework.core.env=DEBUG
logging.level.org.springframework.boot.context.config=DEBUG

Verify active profiles programmatically:

@Component
public class ProfileVerificationComponent {

    @Autowired
    private Environment environment;

    @PostConstruct
    public void verifyProfiles() {
        log.info("Active profiles: {}", Arrays.toString(environment.getActiveProfiles()));
        log.info("Default profiles: {}", Arrays.toString(environment.getDefaultProfiles()));
    }
}

In non-production environments, the Actuator /actuator/env endpoint is one of the best tools for debugging why a profile or property value resolved the way it did.

management:
  endpoints:
    web:
      exposure:
        include: env,health,info

Advanced profile techniques

The @Profile annotation supports boolean expressions using & (AND), | (OR), and ! (NOT). This lets you describe precise activation rules without inventing too many profile names.

@Configuration
@Profile("production & !debug & (mysql | postgresql)")
public class ProductionDatabaseConfig {
    ...
}

@Component
@Profile("!test")
public class ExternalNotificationService {
    ...
}

For custom auto-configuration libraries, combine @ConditionalOnProperty with @Profile when both environment and capability checks matter:

@Configuration
@Profile("metrics")
@ConditionalOnClass(PrometheusMeterRegistry.class)
public class MetricsAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MeterRegistry meterRegistry() {
        return new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
    }
}

Do not try to switch profiles dynamically after the application context is already running. If you need dynamic behavior at runtime, use feature flags or @ConditionalOnProperty within a stable profile setup instead.