Install the Java agent with Gradle

This page covers installing the New Relic Java agent using Gradle. Gradle tasks powered by the de.undercouch.download plugin fetch and unpack newrelic-java.zip into your project directory.

Compatibility and requirements

Supported

Java 8, 11, 17, 21, 24, 25, and 26 (Java 7 supported on agent v6.5.4 and earlier only)
Gradle 6.x or higher
de.undercouch.download plugin version 5.3.0 or higher
Any supported app server or standalone JVM process that accepts a -javaagent argument
See compatibility and requirements for supported framework and library version ranges

Not supported

Running alongside other APM agents — the Java agent cannot guarantee correct behavior when another APM agent is active in the same JVM

You need

A New Relic account and
A JVM with SHA-2 (256-bit) SSL support
A Gradle project with build.gradle

Install

Add the download plugin

Add the de.undercouch.download plugin to the plugins block of your build.gradle:

plugins {
    id "de.undercouch.download" version "5.3.0"
}

Add download and unzip tasks

Add two tasks to build.gradle — one to download the agent zip and one to unpack it:

task downloadNewrelic(type: Download) {
    mkdir 'newrelic'
    src 'https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip'
    dest file('newrelic')
}

task unzipNewrelic(type: Copy) {
    from zipTree(file('newrelic/newrelic-java.zip'))
    into rootDir
}

This places the agent files in a newrelic/ directory at the project root, containing:

newrelic.jar — the Java agent
newrelic.yml — the agent configuration file
newrelic-api.jar — the Java agent API jar
README

Run the tasks

Execute both tasks to download and unpack the agent:

bash

$./gradlew downloadNewrelic
$./gradlew unzipNewrelic

Pass the `-javaagent` argument

Add the -javaagent JVM argument pointing to newrelic.jar when starting your application. The exact method depends on your app server — see Pass the JVM argument for your server for server-specific instructions.

For a Spring Boot jar, for example:

bash

$java -javaagent:/path/to/newrelic/newrelic.jar -jar my-app.jar

Configure

Edit newrelic/newrelic.yml and set two required values:

license_key: 'YOUR_LICENSE_KEY'
app_name: 'My Application'

The agent reads newrelic.yml from the same directory as newrelic.jar at startup. You can also override any setting using Java system properties (e.g. -Dnewrelic.config.license_key=YOUR_KEY) or environment variables.

See Java agent configuration for all available options.

Verify your install

Restart your application. Send at least two requests, then wait 2–3 minutes and your app appears in APM & services.

If no data appears after five minutes, see No data appears (Java).

Compatibility and requirements .css-21sua1{background:none;border:none;width:0;padding:0;}