Everyone has to start somewhere and if you’re new to Gradle, this is where to begin.

Before you start

In order to use Gradle effectively, you need to know what it is and understand some of its fundamental concepts. So before you start using Gradle in earnest, we highly recommend you read What is Gradle?.

Even if you’re experienced with using Gradle, we suggest you read the section 5 things you need to know about Gradle as it clears up some common misconceptions.

Installation

If all you want to do is run an existing Gradle build, then you don’t need to install Gradle if the build has a Gradle Wrapper, identifiable via the gradlew and/or gradlew.bat files in the root of the build. You just need to make sure your system satisfies Gradle’s prerequisites.

Android Studio comes with a working installation of Gradle, so you don’t need to install Gradle separately in that case.

In order to create a new build or add a Wrapper to an existing build, you will need to install Gradle according to these instructions. Note that there may be other ways to install Gradle in addition to those described on that page, since it’s nearly impossible to keep track of all the package managers out there.

Try Gradle

Actively using Gradle is a great way to learn about it, so once you’ve installed Gradle, try one of the introductory hands-on tutorials:

There are also many other tutorials and guides available, which you can filter by category — for example Fundamentals.

Command line vs IDEs

Some folks are hard-core command-line users, while others prefer to never leave the comfort of their IDE. Many people happily use both and Gradle endeavors not to discriminate. Gradle is supported by several major IDEs and everything that can be done from the command line is available to IDEs via the Tooling API.

Android Studio and IntelliJ IDEA users should consider using Kotlin DSL build scripts for the superior IDE support when editing them.

Executing Gradle builds

If you follow any of the tutorials linked above, you will execute a Gradle build. But what do you do if you’re given a Gradle build without any instructions?

Here are some useful steps to follow:

  1. Determine whether the project has a Gradle wrapper and use it if it’s there — the main IDEs default to using the wrapper when it’s available.

  2. Discover the project structure.

    Either import the build with an IDE or run gradle projects from the command line. If only the root project is listed, it’s a single-project build. Otherwise it’s a multi-project build.

  3. Find out what tasks you can run.

    If you have imported the build into an IDE, you should have access to a view that displays all the available tasks. From the command line, run gradle tasks.

  4. Learn more about the tasks via gradle help --task <taskname>.

    The help task can display extra information about a task, including which projects contain that task and what options the task supports.

  5. Run the task that you are interested in.

    Many convention-based builds integrate with Gradle’s lifecycle tasks, so use those when you don’t have something more specific you want to do with the build. For example, most builds have clean, check, assemble and build tasks.

    From the command line, just run gradle <taskname> to execute a particular task. You can learn more about command-line execution in the corresponding user manual chapter. If you’re using an IDE, check its documentation to find out how to run a task.

Gradle builds often follow standard conventions on project structure and tasks, so if you’re familiar with other builds of the same type — such as Java, Android or native builds — then the file and directory structure of the build should be familiar, as well as many of the tasks and project properties.

For more specialized builds or those with significant customizations, you should ideally have access to documentation on how to run the build and what build properties you can configure.

Authoring Gradle builds

Learning to create and maintain Gradle builds is a process, and one that takes a little time. We recommend that you start with the appropriate core plugins and their conventions for your project, and then gradually incorporate customizations as you learn more about the tool.

Here are some useful first steps on your journey to mastering Gradle:

  1. Try one or two basic tutorials to see what a Gradle build looks like, particularly the ones that match the type of project you work with (Java, native, Android, etc.).

  2. Make sure you’ve read 5 things you need to know about Gradle!

  3. Learn about the fundamental elements of a Gradle build: projects, tasks, and the file API.

  4. If you are building software for the JVM, be sure to read about the specifics of those types of projects in Building Java & JVM projects and Testing in Java & JVM projects.

  5. Familiarize yourself with the core plugins that come packaged with Gradle, as they provide a lot of useful functionality out of the box.

  6. Learn how to author maintainable build scripts and best organize your Gradle projects.

The user manual contains a lot of other useful information and you can find more tutorials on various Gradle features among the Gradle Guides.

Integrating 3rd-party tools with Gradle

Gradle’s flexibility means that it readily works with other tools, such as those listed on our Gradle & Third-party Tools page.

There are two main modes of integration:

  • A tool drives Gradle — uses it to extract information about a build and run it — via the Tooling API

  • Gradle invokes or generates information for a tool via the 3rd-party tool’s APIs — this is usually done via plugins and custom task types

Tools that have existing Java-based APIs are generally straightforward to integrate. You can find many such integrations on Gradle’s plugin portal.