Maven Profiles

A profile has an id and, optionally, an activation section plus the content it applies. There are two places to declare one:

The profiles.xml file that Maven 2 read next to the POM is no longer supported. A profiles.xml placed beside a POM was ignored by Maven 3.10.0, with the warning Detected profiles.xml alongside io.tidepool:t:1, this file is no longer supported and was ignored, please use the settings.xml instead.

A minimal profile for tidepool that switches the station data source and renames the jar:

Together with <station.url>file:data/stations.csv</station.url> in the POM’s own properties and a filtered app.properties resource (see Resources & Filtering), the build with and without the profile gave:

(the lines after the commands are the content of target/classes/app.properties and a listing of the jar.)

Source: Introduction to build profiles: types of profile

A profile in the POM may contain these elements, which replace or extend their namesakes in the POM:

Anything else in build, such as sourceDirectory or outputDirectory, is rejected as a malformed POM. This was run with a profile that contained <build><sourceDirectory>other</sourceDirectory></build>, and Maven 3.9.16, 3.10.0 and 4.0.0-rc-7 all refused to build:

(Maven 4 words the message differently: Encountered 1 problem(s) while processing the POMs.)

A profile in settings.xml is more restricted still, because it cannot be shared with the project’s other developers. Giving a settings profile an element it does not know, such as a build element, does not fail the build in Maven 3.10.0, it prints a warning and ignores the element:

A settings profile that is allowed (properties and a repository) and is made active through activeProfiles:

Run with mvn -s settings-example.xml -q help:evaluate -Dexpression=station.url -DforceStdout the property was https://stations.example.org/team, the value from the settings profile, even though the POM declared another default. It was also the value when the POM profile env-live was added with -Penv-live: a settings profile is applied after the profiles of the POM, so it wins (the order is the subject of Profile order and precedence). Selecting ${project.repositories} showed team-mirror listed before the central repository inherited from the super POM.

Source: Which areas of a POM can be customized by each type of profile?

Maven evaluates profiles when it builds the model of each project, before any lifecycle phase runs. A profile becomes active in exactly one of these ways:

The help:active-profiles goal of the Help plugin lists the profiles that are really active for each project of a build, and where each one was declared. It is the first thing to run when a profile "does not work".

A profile that would otherwise be active, including an activeByDefault one or one from activeProfiles, can be switched off on the command line by putting ! or - before its id:

The ! is special for most shells, so quote it or escape it; there is also a bug in the command-line parser (CLI-309) with values that start with a minus, which is why the second form, -P=-id, is recommended. Run on Maven 3.10.0, -P '!jdk21plus' removed jdk21plus from the list and left the others.

What happens when the id does not exist differs by release:

Maven 3 warns and goes on, so a typo such as -Pdeploy-prod silently builds without the profile. Maven 4 (release candidate) fails the build, and a profile that may legitimately be missing is prefixed with ?: -P '?nope' printed The requested optional profiles [nope] could not be activated or deactivated because they do not exist. as an INFO message and continued. On Maven 3.9.16 and 3.10.0 the ? is not recognized, and -P '?nope' still produced the warning, with the id ?nope. The prefix also works for deactivation in Maven 4: -P '!?nope,!os-arch' printed the same INFO message for nope and deactivated os-arch.

Source: Introduction to build profiles: Deactivating a profile, Explicit profile activation

When several profiles are active in the same POM, every element they declare overrides the POM’s own element of the same name, or extends it if it is a collection. If two active profiles set the same thing, the one declared later in the POM wins; the order of the ids in -P and the order in which they were activated make no difference. A scratch POM had a property region and a repository in the POM, and the profiles first and second, each setting region and adding a repository. With -Psecond,first:

and the repositories in the effective POM (mvn help:effective-pom -Psecond,first), before the ones from the super POM, were:

The repository of the last declared profile comes first, then those of earlier profiles, and the POM’s own come last. The order of a repository list matters, since Maven asks them in that order (see Repositories, Mirrors & Repository Managers). Profiles of settings.xml are applied after the POM ones, which is why the settings profile won in the earlier example.

Profile ids are matched per project. In a multi-module build, -Pfast was active in the parent and in both children, and the child b that declared its own fast profile had two: its own and the one inherited from the parent:

Implicit activation, in contrast, looks only at the profile’s own project: a JDK profile of the parent is evaluated for each child independently.

Source: Introduction to build profiles: Profile order

The commands that answer "which profile is on?":

The first is the quick check, and the second shows the result of the profiles. Both are part of the Help plugin; see Plugins & Their Configuration for plugin goals invoked from the command line.

Source: Introduction to build profiles: How can I tell which profiles are in effect during a build?

Maven 4 (release candidate) adds a condition element to activation. It holds an expression, so a profile can be activated by logic that the older jdk, os, property and file elements cannot say, including "this or that" and string tests. The POM must declare model version 4.1.0 (the same profile in a 4.0.0 POM failed with the model contains elements that require a model version of 4.1.0):

mvn help:active-profiles on Maven 4.0.0-rc-7 listed csv-present only, and with -Dtide.site=pier it listed all three; with -Dtide.site=Pier only csv-present and site-contains. The == comparison is case sensitive, and || also works: ${tide.site} == 'pier' || ${tide.site} == 'dock' was active for -Dtide.site=dock and inactive for quay. The condition language is documented only in the issue MNG-8286, so the functions that follow were read from the 4.0.0-rc-7 implementation, and only those used above were run: length, upper, lower, substring, indexOf, contains, matches, not, if, exists, missing and inrange (which takes a version and a range). The implementation also reads ${project.basedir}, ${project.rootDirectory}, ${project.artifactId} and ${project.packaging}, besides system and user properties. A bare name that is not a variable, such as java.version without ${}, fails with Error parsing profile activation condition: Unknown variable: java.version. The other Maven 4 changes are on What’s New in Maven 4 and Maven 4: POM Model & Consumer POM.

Source: What’s new in Maven 4: Condition-based profile activation, MNG-8286

The classic use of profiles is one codebase deployed to several environments (dev, test, prod) with different configuration. The Maven guide shows the idea with a profile per environment that changes the resource directory or a filtered value, and names the profiles after the property that selects them (env-dev, env-test, env-prod for -Denv=dev, and so on), so the command line is easy to guess. The tidepool example earlier is that approach with a single property.

The guide itself says the technique is for simple cases, "a single file or a small set of files that vary for each environment". The fundamental problem is that it builds a different artifact for each environment: the jar tested in test is not the one shipped to prod. The usual alternatives, which keep one artifact:

A profile that changes only how the build runs, such as one that adds a plugin for coverage, is a good fit. A profile that changes what is in the artifact deserves suspicion.

Source: Guide to building for different environments

The Maven documentation names two main problem areas. Both break the principle that the same POM builds the same way everywhere:

Other traps found on this page:

The Enforcer plugin has rules that can fail a build early, for example when a property that a profile should have set is missing (see Enforcer).

Source: Introduction to build profiles: Profile pitfalls

Ant has no profile concept. Its closest equivalents are properties given on the command line with -D, which win over the build file, and the if and unless attributes of targets (see Ant Properties). Gradle has no profiles either: build logic is code, so a condition is an if in the script, a property read with providers, or a convention plugin that applies a set of settings, and the environment-specific values come from gradle.properties files and -P project properties (see Build Environment & Properties). The mapping of all three tools is on Comparing Ant, Maven & Gradle, and the move from Maven profiles to Gradle is on Migrating from Maven.