---
title: Install the Java agent with Maven
source: https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-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 [#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](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 Maven project with `pom.xml`

## Install [#install]

### Configure Maven to download `newrelic-java.zip` [#install-step-1]

Add the Java agent as a `provided` dependency in your `pom.xml`. Replace `JAVA_AGENT_VERSION` with the [latest Java agent version](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes/current):

````xml
<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 [#install-step-2]

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

````xml
<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`

<CollapserGroup>
  <Collapser id="full-pom-example" title="Full pom.xml example">
    ```xml
    <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>
    ```
  </Collapser>
</CollapserGroup>

````

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

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

````

## Configure [#configure]

Edit `target/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 Gradle](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/java-agent-installation-gradle)
-   [Update the Java agent](https://docs.newrelic.com/docs/apm/agents/java-agent/installation/update-java-agent)