Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 41 ยท Packaging and Multi-module

Profiles and Environments

Learn how Maven profiles switch build settings by property, JDK, OS or file, how resource filtering works per environment, and the pitfalls to avoid.

A single build rarely fits every situation. On a laptop you want fast feedback and a local database; on a CI server you want coverage reports; for a release you want signing and javadoc. A Maven profile is a named bundle of POM changes that is switched on only when you ask for it, or when the build environment matches a condition you describe.

This lesson shows how profiles are declared, the five ways to activate them, how they combine with resource filtering to give each environment its own settings, and which mistakes make builds irreproducible. The runnable stand-in is an activation evaluator written in Java, because the real mvn cannot run on this site. Everything with mvn or XML is read-only; the Java code models the decisions Maven makes.

What a profile can change

Properties Values used by ${...} placeholders.
Dependencies Extra or different libraries.
Plugins Settings and extra executions.
Resources Which files are filtered or copied.

A profile overrides or adds to the main build section.

1 / 2

Declaring a profile

Profiles live in a <profiles> section of the POM. Each has an <id> and then the parts of the build it wants to change:

XML
<properties>
  <app.env>local</app.env>
</properties>

<profiles>
  <profile>
    <id>prod</id>
    <properties>
      <app.env>production</app.env>
    </properties>
    <dependencies>
      <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
        <version>1.14.0</version>
      </dependency>
    </dependencies>
  </profile>
</profiles>

Without any profile, app.env is local. With the prod profile active, the property becomes production and the extra dependency joins the build. The most common way to ask for it is the -P flag (see the command line toolbox):

Terminal
mvn package -Pprod
mvn package -Pprod,ci
mvn package -P '!slow-checks'

A comma-separated list activates several profiles; a leading ! deactivates one that would otherwise switch on automatically. You can see which profiles are active with the help plugin:

Terminal
mvn help:active-profiles
mvn help:all-profiles
mvn help:effective-pom -Pprod

Activation rules

Besides -P, a profile can carry an <activation> block. Maven evaluates it at the start of the build. Any one of these conditions switches the profile on:

XML
<profile>
  <id>java-25</id>
  <activation>
    <jdk>[25,)</jdk>
  </activation>
</profile>

<profile>
  <id>windows-tools</id>
  <activation>
    <os><family>windows</family></os>
  </activation>
</profile>

<profile>
  <id>ci</id>
  <activation>
    <property>
      <name>env.CI</name>
      <value>true</value>
    </property>
  </activation>
</profile>

<profile>
  <id>has-docker</id>
  <activation>
    <file><exists>${basedir}/docker/Dockerfile</exists></file>
  </activation>
</profile>
  • Property: active when a system property (-Dname=value) or environment variable (env.NAME) is set, optionally to a given value. Writing <name>!skipChecks</name> means "active when it is not set".
  • JDK: matches the running Java version. A plain value such as 21 is a prefix match; a range such as [21,25) follows Maven version-range syntax.
  • OS: matches name, family, arch and version of the operating system.
  • File: active when a file exists or is missing. Only ${basedir} and a few system properties work inside the path, not arbitrary POM properties.
  • activeByDefault: a profile with <activeByDefault>true</activeByDefault> is on only while no other profile in the same POM has been activated. That surprises people, as the next section explains.

When an activation block lists several conditions, a modern Maven (3.2.2 and later) requires all of them to match. An explicit -P always wins and ignores the activation block.

The activeByDefault trap

activeByDefault sounds like "always on unless I turn it off", but it is not. The moment any other profile of that POM becomes active (even through a JDK match), the default one quietly switches off. Teams then see their dev settings vanish on CI for no obvious reason.

A more dependable pattern is an explicit property that is on unless you disable it:

XML
<activation>
  <property>
    <name>!release</name>
  </property>
</activation>

This profile is active whenever -Drelease is absent, no matter what else is active. Use activeByDefault only for one simple default, and prefer the negated property when you have several profiles.

Environments through filtering

Resource filtering replaces ${...} placeholders inside files in src/main/resources at build time. Combined with profile properties it gives each environment its own values from one set of files. Switch filtering on in the resources section (see the standard directory layout):

XML
<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

Then src/main/resources/application.properties can contain:

TEXT
environment=${app.env}
build.version=${project.version}

After mvn process-resources -Pprod, the copy in target/classes reads environment=production. Two warnings apply. First, filtering touches every file in the folder, so binary files (images, keystores) can be corrupted; filter only text files and put the rest in a second <resource> with <filtering>false</filtering>. Second, a literal ${ in a shell or template file will be replaced or flagged, so escape it or exclude that file.

Many teams avoid baking environment values into artifacts at all. A better rule of thumb is: build once, configure at runtime through environment variables or config files that the deployment provides. Use profiles for build-time differences (extra plugins, test suites, signing), not for secrets or hostnames.

Profiles in settings.xml

Profiles can also appear in settings.xml (see settings, mirrors and credentials). Those profiles are limited to repository, plugin repository and property settings, and they are the right home for things that belong to a developer's machine, such as a company mirror or a path to a license file. Never put secrets in a POM profile that is committed to version control.

Pitfalls to avoid

  • Profiles that change the artifact. If -Pprod and the default build produce different bytecode or dependencies, the jar you tested is not the jar you ship. Keep profile effects to tools and reports whenever possible.
  • Too many profiles. Each combination multiplies the cases to test. Three independent on/off switches already give eight builds.
  • Hidden activation. OS and file activation make a build behave differently on two machines. Print mvn help:active-profiles in CI logs.
  • Inheritance surprises. Profiles in a parent POM are inherited, but activation is evaluated per POM, so activeByDefault in a parent and a child interact in confusing ways.

A profile activation evaluator

This stand-in models how Maven decides. It knows a build context (system properties, JDK version, OS family, existing files, and the profiles requested on the command line) and a list of profiles with their conditions. It applies the rules above: explicit -P and ! first, then activation conditions where all must match, then activeByDefault only if nothing else is active.

Java Which profiles are active?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that dev (marked activeByDefault) never shows up: the no-release profile (property !release) matches whenever release is absent, and that counts as "something else", which is exactly the trap described above. Delete the no-release line and run again: the laptop now gets dev.

Environment-specific filtering, simulated

The second stand-in does what process-resources does with filtering: it reads a template and replaces ${name} from a property map, where active profile properties override the defaults. Unknown placeholders stay as they are, as in Maven.

Java Filtering with profile properties

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The default run keeps local and a pool of 5; with prod active, the same template yields production and 40. The undefined ${not.defined} survives untouched, which is why a leftover placeholder in a built file is a useful hint that a property was never set.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command activates a profile named ci?

    The -P option takes a comma-separated list of profile ids. The other forms are not Maven options.
  2. 2. A POM has a profile with activeByDefault set to true. When does it switch off?

    activeByDefault applies only while no other profile of that POM is active, even one activated by JDK or property. Use a negated property when you need a stable default.
  3. 3. What is a good use of a profile?

    Profiles suit build-time tooling differences. Secrets do not belong in a committed POM, and an artifact that differs per profile is hard to trust.
  4. 4. Why should you avoid filtering a whole resources folder that contains images or keystores?

    Filtering rewrites file content, which can damage binary data. Put binary files in a separate resource entry with filtering turned off.

Summary

  • A profile is a named set of POM changes: properties, dependencies, plugins and resources.
  • Activate with -P, or through property, JDK, OS or file conditions; several conditions must all match.
  • activeByDefault turns off when another profile of that POM activates; a negated property is more reliable.
  • Combine profile properties with resource filtering for per-environment values, but prefer runtime configuration for hostnames and secrets.
  • Keep profile effects small and visible with mvn help:active-profiles.

Next, learn how to put your build output on a server in Publishing: Install, Deploy and Maven Central.