Gradle assemble task essentials

Gradle assemble task

Learn everything you’ll ever need to know about Gradle’s task for creating artifacts, assemble.

Assemble is a task you run from the command line using ./gradlew assemble in Linux and Mac or gradlew assemble in Windows.

To fully understand assemble you need to know about the 2 types of Gradle tasks:

  1. actionable tasks have some action(s) attached to do work in your build
  2. lifecycle tasks are workflow tasks with no actions attached

Assemble is a lifecycle task with no actions attached. Lifecycle tasks often combine other tasks and are useful to run in your development workflow.

lifecycle task overview

The purpose of assemble is to combine all tasks which produce a distribution or artifact into a single task.

For Maven users out there, assemble is similar to Maven’s package phase. 

Adding assemble to a Gradle project

assemble is added into your Gradle project by the base plugin, which registers standard tasks to ensure consistency.

Tasks added by the base plugin (from Gradle docs)

The base plugin is applied automatically by java and other plugins, so don’t be surprised if you’ve never heard of it.

We’ll apply the base plugin in a Gradle Kotlin build script.

plugins {

When we run the tasks task we see that assemble is in the build tasks group.

$ ./gradlew tasks
Build tasks
assemble - Assembles the outputs of this project.

At this point when we run assemble, it doesn’t do anything.

It’s up to other plugins or you as a build author to configure assemble to depend on the relevant artifact producing tasks.

Tasks that assemble depends on

One example of how this works is the java plugin.

plugins {

This adds a jar task to package compiled classes and resources into a jar file. It also configures assemble to depend on jar.  

So in a Java project when we run assemble, jar runs first, generating a jar file.

The Spring Boot plugin also sets up task dependencies from assemble to its own tasks. 

plugins {
    id("org.springframework.boot") version "2.6.2"

Let’s run assemble, and we see that Gradle runs bootJar first to generate the special Spring Boot fat jar file.

If you have other tasks that generate artifacts, you can hook them into the assemble task by configuring a task dependency. 

val customArtifactTask by tasks.registering {
    doLast {
        // create some custom artifact

tasks.named("assemble") {

Ways to run assemble

So what ways can we run assemble?

You’ve seen the simplest of just passing the full task name with ./gradlew assemble.

But you can also use an abbreviated name of ./gradlew a, saving you 7 precious keystrokes! 😂

In IntelliJ IDEA, the assemble task is in the Gradle tool window under build. Double click it to run.

Assemble also gets run when you run the build task, because of a task dependency added by the base plugin.

Gradle runs assemble then check, the verification task which you can learn all about in this article.

When you run assemble when nothing’s changed in your project, it’s marked as UP-TO-DATE and no work should be done, saving you time.

When to use assemble

That leaves the question then, when should you use assemble?

Well, any time you need to build your application’s artifacts without running any verification tasks. That might be if you want to try out code changes in the generated jar file, but aren’t concerned at the moment about running additional checks.

assemble vs. build

You can also run assemble by running build, but that also runs tests which you might not want.

Running assemble instead of build can be quicker.

assemble vs. jar

Assemble is a superset of all artifact producing tasks, and includes jar which generates your application’s jar file. If jar is the only artifact producing task in your project, then assemble and jar are equivalent.

But it might be a good idea to start using assemble now, in case you ever add any other artifact producing tasks in the future.

To learn more about the Gradle fundamentals in Java projects, such as the task graph, why not check out my free course Get Going with Gradle?

Get going with Gradle course
Gradle icon

Want to learn more about Gradle?
Check out the full selection of Gradle tutorials.

Gradle assemble task essentials

2 thoughts on “Gradle assemble task essentials

  1. I’ve been spending a couple hours trying to wrap my head around some aspects of gradle and how to use it for what I need. Dozens of SO posts, gradle documentation, and this was the first one that actually explained things from the ground up, starting simple, and giving me the context I needed to solve my problem. Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top


Getting started with Gradle just got A LOT easier!

Get Going with Gradle is the fastest way to a working knowledge of Gradle.

✅ Work effectively in basic Gradle projects
✅ Know how to setup Java projects in Gradle
✅ Understand the Gradle fundamentals

And it's yours today for FREE!

Where shall I send your access details?

Please wait...

Thank you, check your e-mail inbox for all the details!