Master Maven Assembly Plugin: Build Fat JARs, ZIPs, and Custom Distributions

Overview

The maven-assembly-plugin is a Maven plugin that creates a single archive (JAR, ZIP, TAR, etc.) containing the project's compiled classes, dependencies and any additional resources. It is commonly used to build executable “fat JAR” files or custom distribution packages.

Sample Project

Example project repository: https://gitee.com/lhdxhl/springboot-example.git

Configuration Steps

1. Add the plugin to pom.xml

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-assembly-plugin</artifactId>
      <version>3.6.0</version>
      <configuration>
        <descriptors>
          <descriptor>src/main/assembly/custom-assembly.xml</descriptor>
        </descriptors>
        <appendAssemblyId>false</appendAssemblyId>
      </configuration>
      <executions>
        <execution>
          <id>make-assembly</id>
          <phase>package</phase>
          <goals>
            <goal>single</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

2. Write an assembly descriptor

Create src/main/assembly/custom-assembly.xml to define the packaging logic. A minimal example that produces a tar.gz containing the compiled classes, runtime dependencies and selected resources:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>bin</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <useProjectArtifact>true</useProjectArtifact>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
  <fileSets>
    <fileSet>
      <directory>${project.build.directory}/classes</directory>
      <outputDirectory>/</outputDirectory>
    </fileSet>
    <fileSet>
      <directory>src/main/resources</directory>
      <outputDirectory>/config</outputDirectory>
      <includes>
        <include>**/*.properties</include>
        <include>**/*.yaml</include>
        <include>**/log/logback-spring.xml</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

3. Project directory layout

my-app
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com.lm.assembly.AssemblyApplication.java
│   │   └── resources
│   │       └── application.yaml
│   └── test
├── pom.xml
└── src/main/assembly/custom-assembly.xml

4. Build the package

Run the Maven command: mvn clean package assembly:single The generated archive (e.g., my-app.tar.gz or my-app.jar) will be placed in the target/ directory.

Common Packaging Scenarios

ZIP with dependencies

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>zip-with-dependencies</id>
  <formats>
    <format>zip</format>
  </formats>
  <files>
    <file>
      <source>${project.build.directory}/${project.build.finalName}.jar</source>
      <outputDirectory>/</outputDirectory>
    </file>
  </files>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <unpack>false</unpack>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
</assembly>

Resources‑only TAR

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>resources-only</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>src/main/resources</directory>
      <outputDirectory>/config</outputDirectory>
      <includes>
        <include>**/*</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

Full distribution (binaries + scripts)

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>distribution</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <files>
    <file>
      <source>${project.build.directory}/${project.build.finalName}.jar</source>
      <outputDirectory>/bin</outputDirectory>
    </file>
  </files>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/lib</outputDirectory>
      <unpack>false</unpack>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
  <fileSets>
    <fileSet>
      <directory>src/main/scripts</directory>
      <outputDirectory>/bin</outputDirectory>
      <fileMode>0755</fileMode>
      <includes>
        <include>start.sh</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

Multi‑module distribution

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>multi-module-distribution</id>
  <formats>
    <format>zip</format>
  </formats>
  <moduleSets>
    <moduleSet>
      <useAllReactorProjects>true</useAllReactorProjects>
      <includes>
        <include>com.example:*</include>
      </includes>
      <binaries>
        <outputDirectory>/modules</outputDirectory>
        <unpack>false</unpack>
      </binaries>
    </moduleSet>
  </moduleSets>
</assembly>

Source‑code archive

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>source-archive</id>
  <formats>
    <format>zip</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>src</directory>
      <outputDirectory>/src</outputDirectory>
      <includes>
        <include>**/*.java</include>
        <include>**/*.xml</include>
        <include>**/*.properties</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

Applicable Scenarios

Executable JAR : bundle compiled classes and all runtime dependencies into a single JAR.

Multi‑format packaging : generate ZIP, TAR or other archive types as required.

Resource archives : package specific configuration files or templates separately.

Full distribution bundles : include binaries, libraries, configuration files and startup scripts.

Conclusion

The maven-assembly-plugin provides a flexible way to create custom archives for a wide range of deployment needs. By defining appropriate assembly descriptors, developers can precisely control the contents and format of the final package, whether it is a fat JAR, a resource‑only archive, a multi‑module distribution, or a complete deployment bundle.