Maven Profiles vs. Filtering vs. Separate POMs: Choosing How to Handle Environment-Specific Builds

You need one build that produces a developer-friendly artifact locally and a production-ready artifact in CI — different database drivers, different resource values, maybe different plugin executions — without forking your pom.xml into per-environment copies. Maven gives you three supported ways to do this, and they solve different problems. Picking the wrong one is how teams end up with a prod-pom.xml that drifts out of sync, or a filtering setup that can't actually change a dependency.

The short version: use profiles when the environment changes the build model (dependencies, plugins, properties), use resource filtering when only config file values change, and reserve separate POMs or modules for genuinely divergent deliverables. The rest of this guide compares them and shows a working profile setup with validation commands.

The decision and its constraints

Before choosing, fix your constraints. The common ones:

• One maintainable pom.xml — no copy-pasted variants that drift.
• Activation must be explicit and auditable, especially in CI.
• The number of environments is small (typically dev, prod, maybe staging). If you have many orthogonal variations, no Maven mechanism will save you from combinatorial builds.
• Local and CI builds must resolve the same model for a given profile.

Comparing the three supported options

The trade-off that decides most cases: filtering is the right tool when the artifact is identical and only its bundled configuration differs — but many teams reach for it when they actually need a different dependency (say, H2 for dev, PostgreSQL for prod), which filtering cannot express. Conversely, profiles are overkill if all you need is a different JDBC URL in a properties file. Separate POMs only win when the environments produce genuinely different deliverables, not the same app with different wiring.

A concrete profile implementation

Assume Maven 3.8+ and a single-module project. The goal: H2 on the classpath for dev, PostgreSQL for prod, and tests skipped only in prod (a questionable practice in general, but a common requirement — shown here because it demonstrates plugin-property control).

<profiles>
  <profile>
    <id>dev</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
      <skipTests>false</skipTests>
    </properties>
    <dependencies>
      <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
      </dependency>
    </dependencies>
  </profile>
  <profile>
    <id>prod</id>
    <properties>
      <skipTests>true</skipTests>
    </properties>
    <dependencies>
      <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
      </dependency>
    </dependencies>
  </profile>
</profiles>

Two things to notice. First, activeByDefault on dev is a convenience for local work — but it is deactivated as soon as any other profile in the same POM is activated, which is a frequent source of confusion. Second, note that activeByDefault profiles are also disabled when a profile is activated via -P, so mvn -Pprod gives you prod only, not dev+prod. That is usually what you want, but verify it rather than assume it.

Validating the result

Run these from the project root; no special permissions needed. Never trust the profile XML alone — audit the merged model.

1. mvn help:active-profiles and mvn help:active-profiles -Pprod — confirms which profiles are actually active with and without explicit activation. Expected: dev by default, prod only when requested.
2. mvn help:effective-pom -Pprod — inspects the fully merged model. Check that the PostgreSQL dependency appears and H2 does not, and that skipTests resolved to true.
3. mvn -Pdev dependency:tree and mvn -Pprod dependency:tree — confirms environment-specific artifacts appear only where intended in the resolved graph, including transitives.
4. mvn -Pprod clean verify — the end-to-end check that the prod build actually succeeds with its own model.

In CI, add an explicit guard so a missing -P flag fails loudly instead of silently building the dev model:

mvn help:active-profiles | grep -q "prod" || { echo "prod profile not active"; exit 1; }

Run this in your CI job's shell before the main build. The risk it mitigates is real: a plugin declared only inside a profile runs only when that profile is active, so a misconfigured CI job can skip steps without any error.

Limitations and pitfalls

• Merging order surprises. Profiles from parent POMs, settings.xml, and the command line all merge; later or external definitions can override earlier ones. help:effective-pom is the only reliable source of truth.
• Combinatorial explosion. If you find yourself activating -Pprod,mysql,linux,java17, profiles are the wrong abstraction — that's four orthogonal axes. Keep profiles few, named by purpose, and document their activation conditions in the README.
• Profiles don't follow the artifact. A published artifact's consumers don't see your profiles; anything environment-specific baked into the build must be resolved before deploy. If different environments need different runtime behavior from the same artifact, that's an application-configuration problem (environment variables, config servers), not a Maven problem.
• settings.xml profiles reduce reproducibility. A profile activated from a developer's local settings file won't exist in CI. Prefer POM-local profiles with explicit -P activation for anything the build depends on.

The practical rule: start with filtering if only values change, graduate to profiles when the model changes, and only split POMs when the deliverables themselves diverge. Then prove the choice with help:effective-pom and dependency:tree per profile — those two commands catch nearly every profile mistake before it reaches CI.