{"id":235,"date":"2026-10-13T00:41:25","date_gmt":"2026-10-13T00:41:25","guid":{"rendered":"http:\/\/www.scmgalaxy.com\/tutorials\/2010\/04\/14\/profiles-in-maven\/"},"modified":"2026-10-13T00:41:25","modified_gmt":"2026-10-13T00:41:25","slug":"profiles-in-maven","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/profiles-in-maven\/","title":{"rendered":"Maven Profiles in Practice: Definition, Activation, and Reliable Multi-Environment Builds"},"content":{"rendered":"\n

Maven profiles let you keep one pom.xml<\/code> while adapting builds for different environments such as local development, CI, testing, or production. You will learn where profiles can be defined, how activation works, and how to use profiles without hurting build portability.<\/p>\n\n\n\n

Originally published on 2010-04-14; fully revised and updated.<\/em><\/p>\n\n\n\n

Reference basis: Apache Maven User Guide concepts for profiles, updated for practical DevOps usage. Original post: Profiles in Maven \u2013 How to Build Maven Profile?<\/a>. Maven project site: Apache Maven<\/a>.<\/p>\n\n\n\n

\"Profiles<\/p>\n\n\n\n

What Maven profiles are and when to use them<\/h2>\n\n\n\n

A profile is a conditional block of Maven configuration. When active, it can add or override parts of the build (properties, dependencies, plugins, repositories, and more) for a specific context.<\/p>\n\n\n\n

  • Use profiles when builds differ by environment (for example, local vs CI).<\/li>
  • Use profiles to avoid maintaining multiple POM files with -f<\/code>.<\/li>
  • Prefer profiles for complementary<\/em> configuration, not for creating unrelated builds from one project.<\/li><\/ul>\n\n\n\n

    Where Maven profiles are defined<\/h2>\n\n\n\n

    Maven supports project, user, and global profile locations. Older Maven-era material also mentions a separate profiles.xml<\/code> descriptor.<\/p>\n\n\n\n

    Profile type<\/th>Defined in<\/th>Scope<\/th>Typical use<\/th><\/tr><\/thead>
    Per-project<\/td>pom.xml<\/code><\/td>Shared in source control<\/td>Project-specific dependencies, plugins, and properties<\/td><\/tr>
    Per-user<\/td>${user.home}\/.m2\/settings.xml<\/code><\/td>Single developer or CI agent<\/td>Local paths, credentials references, machine-specific defaults<\/td><\/tr>
    Global<\/td>${maven.home}\/conf\/settings.xml<\/code><\/td>All users of one Maven installation<\/td>Organization-wide defaults on managed hosts<\/td><\/tr>
    Legacy descriptor<\/td>profiles.xml<\/code> in project base directory<\/td>Historical pattern<\/td>Seen in older Maven 2 documentation; verify current support<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    How profile activation works<\/h2>\n\n\n\n

    Profiles can be activated explicitly from the command line or automatically through activation rules (JDK, OS, property, file presence\/missing, or active-by-default behavior).<\/p>\n\n\n\n

    \nflowchart TD\n    A[Run mvn command] --> B[Load project profiles]\n    B --> C[Load user and global settings profiles]\n    C --> D{Any -P flags}\n    D -- Yes --> E[Apply explicit activate or deactivate]\n    D -- No --> F[Evaluate activation rules]\n    F --> G[Check jdk os property file conditions]\n    G --> H[Apply activeByDefault when applicable]\n    E --> I[Merge into effective pom]\n    H --> I\n    I --> J[Execute build lifecycle]\n<\/pre>\n\n\n\n
    Important behavior:<\/strong> a profile with activeByDefault<\/code> is typically deactivated when another profile in the same POM becomes active.<\/p>\n\n\n\n
    Activation method<\/th>How to set it<\/th>Example<\/th>Best use<\/th><\/tr><\/thead>
    Explicit CLI<\/td>-P<\/code> option<\/td>-Pdev,test<\/code><\/td>Temporary run-time choice<\/td><\/tr>
    Settings default<\/td><activeProfiles><\/code> in settings.xml<\/td><activeProfile>corp<\/activeProfile><\/code><\/td>User or machine defaults<\/td><\/tr>
    System property<\/td><activation><property><\/code><\/td>-Denvironment=test<\/code><\/td>CI-driven environment selection<\/td><\/tr>
    JDK<\/td><activation><jdk><\/code><\/td>17<\/code> or range<\/td>JDK-specific build behavior<\/td><\/tr>
    OS<\/td><activation><os><\/code><\/td><family>Windows<\/family><\/code><\/td>Platform-specific tooling<\/td><\/tr>
    File exists\/missing<\/td><activation><file><\/code><\/td><missing>target\/...<\/missing><\/code><\/td>Generated-artifact or workspace checks<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Example profile configuration in pom.xml<\/h2>\n\n\n
    <profiles<\/span>><\/span>\n  <profile<\/span>><\/span>\n    <id<\/span>><\/span>dev<\/id<\/span>><\/span>\n    <activation<\/span>><\/span>\n      <activeByDefault<\/span>><\/span>true<\/activeByDefault<\/span>><\/span>\n    <\/activation<\/span>><\/span>\n    <properties<\/span>><\/span>\n      <app.env<\/span>><\/span>dev<\/app.env<\/span>><\/span>\n    <\/properties<\/span>><\/span>\n  <\/profile<\/span>><\/span>\n\n  <profile<\/span>><\/span>\n    <id<\/span>><\/span>test<\/id<\/span>><\/span>\n    <activation<\/span>><\/span>\n      <property<\/span>><\/span>\n        <name<\/span>><\/span>environment<\/name<\/span>><\/span>\n        <value<\/span>><\/span>test<\/value<\/span>><\/span>\n      <\/property<\/span>><\/span>\n    <\/activation<\/span>><\/span>\n    <properties<\/span>><\/span>\n      <app.env<\/span>><\/span>test<\/app.env<\/span>><\/span>\n    <\/properties<\/span>><\/span>\n  <\/profile<\/span>><\/span>\n\n  <profile<\/span>><\/span>\n    <id<\/span>><\/span>windows-build<\/id<\/span>><\/span>\n    <activation<\/span>><\/span>\n      <os<\/span>><\/span>\n        <family<\/span>><\/span>Windows<\/family<\/span>><\/span>\n      <\/os<\/span>><\/span>\n    <\/activation<\/span>><\/span>\n  <\/profile<\/span>><\/span>\n\n  <profile<\/span>><\/span>\n    <id<\/span>><\/span>generate-wsdl<\/id<\/span>><\/span>\n    <activation<\/span>><\/span>\n      <file<\/span>><\/span>\n        <missing<\/span>><\/span>target\/generated-sources\/wsdl.marker<\/missing<\/span>><\/span>\n      <\/file<\/span>><\/span>\n    <\/activation<\/span>><\/span>\n  <\/profile<\/span>><\/span>\n<\/profiles<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    For environment variables, Maven exposes them as properties prefixed with env.<\/code> (for example, env.FOO<\/code>).<\/p>\n\n\n\n
    Command-line usage: activate, deactivate, inspect<\/h2>\n\n\n
    # Activate one or more profiles<\/span>\nmvn clean package -Pdev\nmvn clean verify -Pdev,test\n\n# Trigger property-based activation<\/span>\nmvn clean verify -Denvironment=test\n\n# Deactivate profiles (quote ! in shells that treat it specially)<\/span>\nmvn clean package -P '!dev'<\/span>\nmvn clean package -P '!dev,!windows-build'<\/span>\n\n# Inspect profile resolution<\/span>\nmvn help:active-profiles\nmvn help:all-profiles<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Using settings.xml for user or machine-specific profiles<\/h2>\n\n\n
    <settings<\/span>><\/span>\n  <activeProfiles<\/span>><\/span>\n    <activeProfile<\/span>><\/span>corp-network<\/activeProfile<\/span>><\/span>\n  <\/activeProfiles<\/span>><\/span>\n\n  <profiles<\/span>><\/span>\n    <profile<\/span>><\/span>\n      <id<\/span>><\/span>corp-network<\/id<\/span>><\/span>\n      <properties<\/span>><\/span>\n        <repo.mirror.enabled<\/span>><\/span>true<\/repo.mirror.enabled<\/span>><\/span>\n      <\/properties<\/span>><\/span>\n    <\/profile<\/span>><\/span>\n  <\/profiles<\/span>><\/span>\n<\/settings<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    Keep secrets and machine-only values in settings files, not in project pom.xml<\/code>.<\/p>\n\n\n\n
    Best practices for reliable team builds<\/h2>\n\n\n\n
    • Prefer profile-driven properties over hardcoded absolute filesystem paths.<\/li>
    • Use clear profile IDs such as dev<\/code>, test<\/code>, ci<\/code>, prod<\/code>.<\/li>
    • Avoid unnecessary changes to artifact coordinates across profiles.<\/li>
    • Document which profiles CI uses, and verify with mvn help:active-profiles<\/code>.<\/li>
    • Keep team-shared behavior in pom.xml<\/code>; keep user\/machine behavior in settings.xml<\/code>.<\/li>
    • Treat legacy profiles.xml<\/code> usage as technical debt and confirm support before relying on it.<\/li><\/ul>\n","protected":false},"excerpt":{"rendered":"
      Maven profiles let you customize one build for multiple environments without cloning POM files. This guide covers profile types, activation methods, CLI usage, and team-safe best practices.<\/p>\n","protected":false},"author":1,"featured_media":4268,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[29],"tags":[3864,3863,3870,161,3865,3867,3868,3866,3869,3861,3860,3862,818],"class_list":["post-235","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-maven","tag-build-profile","tag-build-profiles-in-maven","tag-how-to-build-maven-profile","tag-maven","tag-maven-profile-guide","tag-maven-profile-instructions","tag-maven-profile-references","tag-maven-profile-tutorials","tag-maven-profile-user-guide","tag-maven-profiles","tag-profiles","tag-profiles-in-maven","tag-trigger"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/235","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=235"}],"version-history":[{"count":3,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/235\/revisions"}],"predecessor-version":[{"id":79065,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/235\/revisions\/79065"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media\/4268"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=235"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=235"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=235"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}