---
title: Install the Java agent with Gradle
source: https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-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 [#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](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/compatibility-requirements-java-agent) 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 license key
-   A JVM with SHA-2 (256-bit) SSL support
-   A Gradle project with `build.gradle`

## Install [#install]

### Add the download plugin [#install-step-1]

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

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

````

### Add download and unzip tasks [#install-step-2]

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

````groovy
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 [#install-step-3]

Execute both tasks to download and unpack the agent:

````bash
./gradlew downloadNewrelic
./gradlew unzipNewrelic
```

````

### Pass the `-javaagent` argument [#install-step-4]

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](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-app-servers#install-step-3) for server-specific instructions.

For a Spring Boot jar, for example:

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

````

## Configure [#configure]

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

```yaml
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](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file) for all available options.

## Verify your install [#verify]

Restart your application. Send at least two requests, then wait 2–3 minutes and your app appears in [APM & services](https://one.newrelic.com/nr1-core?filters=%28domain%20IN%20%28%27APM%27%2C%20%27EXT%27%29%20AND%20type%20IN%20%28%27APPLICATION%27%2C%20%27SERVICE%27%29%29).

If no data appears after five minutes, see [No data appears (Java)](https://docs.newrelic.com/docs/apm/agents/java-agent/troubleshooting/no-data-appears-java).

## Related articles [#related-articles]

-   [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file)
-   [Compatibility and requirements](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/compatibility-requirements-java-agent)
-   [Install with Maven](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-maven)
-   [Update the Java agent](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/update-java-agent)