Maven Assembly Plugin

Do you want to create a binary distribution from a Maven project that includes supporting scripts, configuration files, and all runtime dependencies? You need to use the Assembly Plugin to create a distribution for your project.

This plugin generates "assemblies". It is the equivalent of the Maven 1 distribution plug-in. This plugin provides the capability to create binary and source distributions. These distributions (assemblies) are defined using an assembly descriptor. You can write your own descriptor to create a custom assembly, or you can reuse one of the three pre-defined assemblies.

Currently it can create distributions in the following formats:

  • zip
  • tar.gz
  • tar.bz2
  • jar
  • dir
  • war
  • and any other format that the ArchiveManager has been configured for

To use the Assembly Plugin in Maven 2, you simply need to:

  • choose or write the assembly descriptor to use,
  • configure the Assembly Plugin in your project's pom.xml, and
  • run "mvn assembly:assembly" on your project.

To write your own custom assembly, you will need to refer to the Assembly Descriptor Format reference.

What is an Assembly?

An "assembly" is a group of files, directories, and dependencies that are assembled into an archive format and distributed. For example, assume that a Maven project defines a single JAR artifact that contains both a console application and a Swing application. Such a project could define two "assemblies" that bundle the application with a different set of supporting scripts and dependency sets. One assembly would be the assembly for the console application, and the other assembly could be a Swing application bundled with a slightly different set of dependencies.

The Assembly Plugin provides a descriptor format which allows you to define an arbitrary assembly of files and directories from a project. For example, if your Maven 2 project contains the directory "src/main/bin", you can instruct the Assembly Plugin to copy the contents of this directory to the "bin" directory of an assembly and to change the permissions of the files in the "bin" directory to UNIX mode 755. The parameters for configuring this behavior are supplied to the Assembly Plugin by way of the assembly descriptor.

The Maven Assembly Plugin

The Assembly Plugin for Maven 2.0 is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.

Your project build can build distribution assemblies easily, using one of the convenient, prefabricated assembly descriptors. These descriptors handle many common operations, such as packaging a project's artifact along with its dependencies in a single jar. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.

Goals Overview

The Assembly Plugin has six goals:

  • assembly:assembly Assembles an application bundle or distribution based on an assembly descriptor into an archive of a chosen format. Executed from the command-line.
  • assembly:attached Assembles an application bundle or distribution from an assembly descriptor into an archive of a chosen format. Executed within the Maven Lifecycle.
  • assembly:directory Assembles an application bundle from an assembly descriptor or distribution into a directory. Executed from the command-line.
  • assembly:directory-inline Assembles an application bundle or distribution into a directory. Executed within the Maven Lifecycle.
  • assembly:unpack Assembles an application bundle or distribution from an assembly descriptor into an archive of a chosen format but with the dependencies unpacked inside the archive.
  • assembly:single An assembly mojo created as a work-around for lifecycle issues until addressed in the Maven 2.1 release.


Instructions on how to use the Assembly Plugin can be found here.


To provide you with better understanding on some usages of the Assembly Plugin, you can take a look into the examples which can be found here.