How is AutoConfiguration.imports discovered (or the legacy spring.factories)?

Boot finds auto-configuration classes by reading a plain-text list inside each jar — in Boot 3 that file is META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. It's just fully-qualified class names, one per line. There's no classpath-wide scan for @AutoConfiguration annotations; the list is explicit and that's deliberate (faster startup, predictable).

The Boot 3 file

# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.acme.audit.AuditAutoConfiguration
com.acme.audit.AuditWebAutoConfiguration

@EnableAutoConfiguration imports AutoConfigurationImportSelector, which collects these class names from every jar on the classpath, deduplicates and orders them, then hands the list to the context. Each named class is then evaluated against its @Conditional guards — listing a class only makes it a candidate, conditions decide whether it actually runs.

The legacy mechanism (Boot 2 and earlier)

Before Boot 3, candidates were declared in META-INF/spring.factories under the EnableAutoConfiguration key:

# META-INF/spring.factories  (Boot 2.x)
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.acme.audit.AuditAutoConfiguration,\
com.acme.audit.AuditWebAutoConfiguration

Why the change

The new format is purpose-built: one file, one concern, simpler to parse and to read. It also pairs with the @AutoConfiguration annotation (Boot 3's replacement for using a bare @Configuration as an auto-config), which carries ordering metadata (before, after).

Generating it for a custom starter

You rarely hand-write the file. Add the processor and annotate your class — the imports file is generated at build time:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure-processor</artifactId>
    <optional>true</optional>
</dependency>

@AutoConfiguration
@ConditionalOnClass(AcmeClient.class)
public class AuditAutoConfiguration { ... }

Discovery order at startup

1. @EnableAutoConfiguration → AutoConfigurationImportSelector.
2. Selector reads all AutoConfiguration.imports files across jars.
3. Candidates are ordered (@AutoConfiguration(before/after), @AutoConfigureOrder) and exclusions applied.
4. Each candidate's @Conditional guards are evaluated; survivors register beans.