The simplest way to use Akka is as a regular library, adding the Akka jars you need to your classpath (in case of a web app, in WEB-INF/lib).

In many cases, such as deploying to an analytics cluster, building your application into a single ‘fat jar’ is needed. When building fat jars, some additional configuration is needed to merge Akka config files, because each Akka jar contains a reference.conf resource with default values.

The method for ensuring reference.conf resources are merged depends on the tooling you use to create the fat jar:

  • sbt: as an application packaged with sbt-native-packager
  • Maven: as an application packaged with a bundler such as jarjar, onejar or assembly
  • Gradle: using the Jar task from the Java plugin

sbt: Native Packager

sbt-native-packager is a tool for creating distributions of any type of application, including Akka applications.

Define sbt version in project/ file:


Add sbt-native-packager in project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.1.5")

Follow the instructions for the JavaAppPackaging in the sbt-native-packager plugin documentation.

Maven: jarjar, onejar or assembly

You can use the Apache Maven Shade Plugin support for Resource Transformers to merge all the reference.confs on the build classpath into one.

The plugin configuration might look like this:


Gradle: the Jar task from the Java plugin

When using Gradle, you would typically use the Jar task from the Java plugin to create the fat jar.

To make sure the reference.conf resources are correctly merged, you might use the Shadow plugin, which might look something like this:

import com.github.jengelman.gradle.plugins.shadow.transformers.AppendingTransformer

plugins {
    id 'java'
    id "com.github.johnrengelman.shadow" version "5.0.0"

shadowJar {
    transform(AppendingTransformer) {
        resource = 'reference.conf'
    with jar

Or when you use the Kotlin DSL:

tasks.withType<ShadowJar> {
    val newTransformer = AppendingTransformer()
    newTransformer.resource = "reference.conf"
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.