Install the Java agent with Maven

This page covers installing the New Relic Java agent using Maven. Maven downloads and unpacks newrelic-java.zip as a build dependency, placing the agent files in your build directory automatically.

Compatibility and requirements

Supported

Java 8, 11, 17, 21, 24, 25, and 26 (Java 7 supported on agent v6.5.4 and earlier only)
Maven 3.x
maven-dependency-plugin 3.1.1 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 Maven project with pom.xml

Install

Configure Maven to download `newrelic-java.zip`

Add the Java agent as a provided dependency in your pom.xml. Replace JAVA_AGENT_VERSION with the latest Java agent version:

<dependency>
    <groupId>com.newrelic.agent.java</groupId>
    <artifactId>newrelic-java</artifactId>
    <version>JAVA_AGENT_VERSION</version>
    <scope>provided</scope>
    <type>zip</type>
</dependency>

Configure Maven to unzip the agent

Add maven-dependency-plugin to the <build><plugins> section of your pom.xml to unpack the agent zip into your build directory:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>3.1.1</version>
    <executions>
        <execution>
            <id>unpack-newrelic</id>
            <phase>package</phase>
            <goals>
                <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
                <includeGroupIds>com.newrelic.agent.java</includeGroupIds>
                <includeArtifactIds>newrelic-java</includeArtifactIds>
                <overWriteReleases>false</overWriteReleases>
                <overWriteSnapshots>false</overWriteSnapshots>
                <overWriteIfNewer>true</overWriteIfNewer>
                <outputDirectory>${project.build.directory}</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

After running mvn package, a newrelic/ folder appears in target/ containing:

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

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.application</groupId>
    <artifactId>my-example-app</artifactId>
    <packaging>war</packaging>
    <version>1.0</version>
    <name>My Example Application</name>
    <dependencies>
        <dependency>
            <groupId>com.newrelic.agent.java</groupId>
            <artifactId>newrelic-java</artifactId>
            <version>JAVA_AGENT_VERSION</version>
            <scope>provided</scope>
            <type>zip</type>
        </dependency>
    </dependencies>
    <build>
        <finalName>my-example-app</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.2.2</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.1.1</version>
                <executions>
                    <execution>
                        <id>unpack-newrelic</id>
                        <phase>package</phase>
                        <goals>
                            <goal>unpack-dependencies</goal>
                        </goals>
                        <configuration>
                            <includeGroupIds>com.newrelic.agent.java</includeGroupIds>
                            <includeArtifactIds>newrelic-java</includeArtifactIds>
                            <overWriteReleases>false</overWriteReleases>
                            <overWriteSnapshots>false</overWriteSnapshots>
                            <overWriteIfNewer>true</overWriteIfNewer>
                            <outputDirectory>${project.build.directory}</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

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/target/newrelic/newrelic.jar -jar my-example-app.jar

Configure

Edit target/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;}