Maven Resources & Filtering

The Resources Plugin (maven-resources-plugin) has three goals that matter, and two of them are bound to the default lifecycle of a jar project:

Source: Resources Plugin: resources:resources

Source: Resources Plugin: resources:testResources

Source: Resources Plugin: resources:copy-resources

The phases come right after generate-sources and process-sources in the lifecycle (see Build Lifecycle), and process-resources runs before compile. So a class that reads a resource at compile time through an annotation processor sees the copied files, and a source generator bound to generate-sources can produce sources that the compiler picks up (see Generated sources).

The default resource directories are src/main/resources and src/test/resources, and the default is no filtering. Start with the smallest possible case: the project below has one plain resource and one that will be filtered, kept in two separate directories (the plugin documentation recommends this split, and the reason is in Binary files).

Declaring <resources> in the POM replaces the default list (it does not add to it), so the first entry is needed to keep src/main/resources.

The source files:

readme.txt contains the single line Plain file: version is ${project.version}. Run the phase:

The long INFO line is the plugin asking you to decide how properties files are encoded; Encoding shows the setting. Only the lines of the plugin were kept above. The result in target/classes:

Three things to notice: the unfiltered file kept its placeholder; a placeholder that Maven cannot resolve (app.unknown) is left as it is without any warning, so a misspelt name silently survives into the JAR; and @...@ works as well as ${...} with the default settings.

Source: Resources Plugin: Filtering

Source: Maven Getting Started Guide: How do I filter resource files?

A <resource> has these elements:

Source: Resources Plugin: Specifying a resource directory

Source: Resources Plugin: Including and excluding files and directories

The next example uses four directories: one with an excluded test script, one filtered, one with a <targetPath> and an <includes> list, and the test resources (which have their own <testResources> list and are copied by resources:testResources in the process-test-resources phase).

src/main/resources held db/schema.sql, db/schema-test.sql, a backup file db/schema.sql~, a .DS_Store file, a .gitignore file and the static/readme.txt file; src/main/docs held guide.md and a .txt file; src/test/resources and src/test/resources-filtered held one properties file each. Running mvn process-test-resources copies the main resources first, because process-resources is an earlier phase:

What this shows:

Everything above is the same on Maven 3.9.16 and 4.0.0-rc-7: the resulting files had identical checksums.

Source: Resources Plugin: fileNameFiltering parameter

Source: Resources Plugin: addDefaultExcludes parameter

Filtering replaces ${name} and @name@ (with name a property) by its value. The value is looked up in this order of precedence, which I established by defining the same name in several places and reading the result:

In addition the environment variables are available with the prefix env. (${env.TIDEPOOL_HOME}), the JVM system properties directly (${java.version}, ${user.home}), and settings values with settings. (${settings.localRepository} gave /home/dev/.m2/repository, or the path given with -Dmaven.repo.local). A bare ${HOME} does not resolve (environment variables need env.), which is also why shell scripts containing ${HOME} survive filtering (see Delimiters and escapes).

A filter file is a Java properties file listed in the <filters> of the build. The next example defines station.default in the POM and in the filter file, db.url only in the filter file, and project.version in the filter file as well:

The POM still has <station.default>SF</station.default>. The resource is:

The POM property (SF) beat the filter file (BOS); the filter file supplied db.url; and, surprisingly, a filter file also beat the project.version of the model (9.9.9 instead of 1.4.0-SNAPSHOT), so a filter file must not define project.* names unless you mean it. Now the command line:

The -D values won over both the POM and the filter file. The same three results were obtained on Maven 3.9.16 and 4.0.0-rc-7.

Source: Resources Plugin: Filtering

By default the plugin recognises two delimiter styles: ${*} (begin ${, end }) and @ (the same token at both ends). Two parameters change that: <delimiters> lists delimiters in the form begin*end (or just @ when both are equal) and <useDefaultDelimiters> says whether the default pair stays in force alongside them (default true). <escapeString> (since 2.3) defines a prefix that protects a placeholder.

The test file below mixes the cases:

Filtered with the defaults, then with <escapeString>\</escapeString>, then with <useDefaultDelimiters>false</useDefaultDelimiters> and a single @ delimiter:

What follows from it:

<supportMultiLineFiltering> (since 2.5, default false) controls whether the search for the end token stops at the end of the line, and <escapeWindowsPaths> (since 2.4, default true) escapes backslashes and colons in Windows-style path values so that they survive a properties file.

Source: Resources Plugin: Escape filtering

Source: Resources Plugin: delimiters parameter

Never filter binary files. The reader decodes the file to text using the configured encoding, replaces placeholders, and encodes it again, which breaks any byte sequence that is not valid text. The plugin documentation recommends two directories, one for filtered and one for unfiltered files, and that is the structure used in this page.

As a safety net the plugin never filters files with the extensions jpg, jpeg, gif, bmp and png; more can be added with nonFilteredFileExtensions (since 2.3). The test used a file with PNG-like bytes, invalid UTF-8 bytes and the text build=${project.version}, saved three times as tide.png, tide.dat and tide.bin in a filtered directory:

This script is this page’s own test setup, not an example from the Maven documentation.

MalformedInputException during filtering is the classic sign of a binary file in a filtered directory. The .png was skipped, the .dat was not. Adding the extensions fixes it:

The checksums are the same before and after: the files were copied byte for byte. The failure above is the good outcome. With -Dproject.build.sourceEncoding=ISO-8859-1 (an encoding that can decode any byte) and no nonFilteredFileExtensions, the same files are accepted and silently damaged:

The .dat and .bin copies are 4 bytes shorter (the placeholder was replaced inside the binary data) and have a different checksum; only the .png survived. The same results were seen on Maven 3.9.16 and 4.0.0-rc-7. A binary file that is corrupted this way (a keystore, a font, a Word document, a ZIP file) usually fails far from the build, at run time.

Source: Resources Plugin: Binary filtering

The encoding parameter of the plugin defaults to ${project.build.sourceEncoding}. Set that property in every POM (the examples on this page set it to UTF-8). Without it the plugin uses the platform default, which makes the result depend on the machine; since JDK 18 the default is UTF-8, but MAVEN_OPTS=-Dfile.encoding=ISO-8859-1 was enough to change it in the test. In the test, a filtered file saved in ISO-8859-1 (latin1.properties, with the byte E9 for the letter e with an acute accent) failed under UTF-8:

Setting -Dproject.build.sourceEncoding=ISO-8859-1 made both latin1.properties and a UTF-8 file utf8.properties pass, and both kept their original bytes (decoding and encoding with the same single-byte encoding round-trips every byte). It is a way to get a build to pass; it is not a fix.

The information message seen in the first output is about properties files, which have a history of their own with encodings (the Properties.load method for a byte stream still assumes ISO-8859-1). The propertiesEncoding parameter (since 3.2.0) sets the encoding for filtered *.properties files separately and, when absent, follows encoding, which is what the message says. With <propertiesEncoding>ISO-8859-1</propertiesEncoding> in the plugin configuration and the project encoding at UTF-8, the message disappeared and the two test files were copied with their bytes unchanged:

Choose one encoding for the whole repository, normally UTF-8, convert the odd file once, and set propertiesEncoding to the same value so that the message goes away. The Spring Boot starter parent does this (<propertiesEncoding>${project.build.sourceEncoding}</propertiesEncoding>).

Source: Resources Plugin: Filtering properties files

${maven.build.timestamp} is the time at which Maven started the build, in UTC, formatted by the maven.build.timestamp.format property (default yyyy-MM-dd'T'HH:mm:ss'Z'). It is always "now", even when project.build.outputTimestamp is set (see Security & Reproducible Builds): in the first example app.built=2026-10-16T13:06:17Z was the wall-clock time of the run on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7. Using it in a filtered file therefore makes the output of every build different, and it is not reproducible. The Resources Plugin 3.4.0 and later only rewrite a target file when its content differs (the changeDetection parameter, since 3.5.0, defaults to content; the older default was timestamp). A file with a build time is rewritten at every run, and one without is left alone:

For a stable value use the fixed ${project.build.outputTimestamp} property (an ISO-8601 instant that you set in the POM, usually by the release process) and nothing that reads the clock. A build number or a commit id is a different matter: they come from plugins such as the MojoHaus buildnumber-maven-plugin (3.3.1 on Central) or the commit id of a Git plugin, which put the value in a property that you then filter; I did not run those plugins here.

Source: Resources Plugin: changeDetection parameter

Source: MojoHaus Build Number Maven Plugin

Filtering is not limited to properties. A common use is a small Java class that carries the version and the coordinates, produced from a template by filtering. The template lives in src/main/java-templates (not in src/main/java, so that IDEs do not try to compile the placeholders):

Two executions do the work in the generate-sources phase. resources:copy-resources filters the template into target/generated-sources/java-templates, and the MojoHaus build-helper:add-source goal adds that directory to the compile source roots. Both lines are needed: the Resources Plugin does not know about source roots, and Build Helper does not filter.

Main.java prints BuildInfo.GROUP + ":" + BuildInfo.ARTIFACT + ":" + BuildInfo.VERSION.

The executions run in the order in which they appear in the POM because both are in the same phase; the output above is from Maven 3.10.0 and the same lines (and the same program output) appeared on 3.9.16 and 4.0.0-rc-7. Maven 4.0.0-rc-7 also printed a warning about a missing root directory because the scratch project had no .mvn directory (see Maven 4: What’s New).

The generated directory must be a compile source root, which is why add-source is needed; adding it as a <resource> instead would copy the .java file into the JAR and never compile it. The other common sources of generated code (ANTLR, JAXB, protobuf, OpenAPI) are plugins that add their own source root, so they do not need Build Helper. The "Guide to generating sources" shows the pattern with the ANTLR 4 plugin: bind a plugin to generate-sources and the compiler finds what it wrote. The MojoHaus templating-maven-plugin (3.1.1 on Central) is a ready-made version of the template pattern shown here (a filter-sources goal); it was not run here. Similarly the Apache maven-remote-resources-plugin (3.3.0 on Central) bundles resources (licence and notice files, for example) from other artifacts into a build; it is not run here either.

Source: Guide to generating sources

Source: Build Helper Maven Plugin: add-source

Source: MojoHaus Templating Maven Plugin

Source: Resources Plugin: Copy resources

On Maven 4.0.0-rc-7 the Resources Plugin 3.5.0 and the model version 4.0.0 behave exactly as above; everything on this page was repeated there. The new model version 4.1.0 adds a generic <sources> element to <build> that replaces the separate <resources> and source directory settings. A <source> has a <lang> (java or resources), a <scope> (main or test), a <directory>, <includes>, <excludes>, <targetPath> and the boolean <stringFiltering> that corresponds to <filtering>. This was run on 4.0.0-rc-7 with a POM in namespace http://maven.apache.org/POM/4.1.0:

Writing <filtering> in a <source> is rejected with Unrecognised tag: '{http://maven.apache.org/POM/4.1.0}filtering'. A POM with model version 4.1.0 cannot be built by Maven 3 (see Maven 4: POM Model & Consumer POM), and the 4.1.0 model is part of a release candidate, so keep the 4.0.0 model and <resources> for builds that must also run on Maven 3.

Source: Maven 4.1.0 POM schema (Source type)

Source: Apache Maven: What’s new in Maven 4

Gradle has no default filtering and no default delimiter, so there is no equivalent of the Spring Boot @-only trick. For converting a whole Maven build see Migrating Between Tools. These are descriptions; no Ant or Gradle build was run for this page.

Source: Gradle: Working With Files, Filtering files

Source: Apache Ant: FilterSet

The Maven 2 book that informed these pages describes filtering and the Resources Plugin at the 2.x level. Differences with current releases: