How to Add Local JAR Files to a Maven Project in Java

By the end of this page, you will understand how Maven handles dependencies, why local JAR files are a special case, and the common ways to use them in a Java project. You will also learn which approach is best for short-term use and which one is better for real projects.

Maven manages project dependencies using coordinates such as groupId, artifactId, and version. Normally, Maven downloads libraries from remote repositories like Maven Central, or from your local Maven cache.

A local JAR file becomes a problem when it is not published anywhere Maven can find it. In that case, Maven does not automatically know:

• what the library is called
• what version it is
• where to download it from

There are two main ways developers deal with this:

1. Reference the JAR directly from the filesystem using system scope
2. Install the JAR into the local Maven repository so Maven can treat it like a normal dependency

The second option is usually better because it fits Maven's dependency system.

Why this matters:

• builds become more repeatable
• dependency management stays consistent
• IDE support works better
• CI/CD pipelines are easier to set up later

Using random JAR files copied into a project can work temporarily, but it usually causes problems for teammates and build servers if not handled carefully.

Think of Maven as a librarian.

Normally, you ask for a book using a catalog entry:

• groupId = section of the library
• artifactId = book title
• version = edition

Maven then goes to the shelf or orders the book from another library.

A local JAR file is like having a book that is not in the catalog. You have two choices:

• Point directly to the physical book on your desk using a file path
• Add the book to the catalog first so the librarian can manage it properly

The second option is cleaner, more organized, and works better when other people need the same book.

Option 1: Directly reference a local JAR with system scope

This approach points to a JAR file on disk.

<dependency>
  <groupId>com.example</groupId>
  <artifactId>my-local-lib</artifactId>
  <version>1.0.0</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/lib/my-local-lib-1.0.0.jar</systemPath>
</dependency>

Example project structure:

my-app/
├── pom.xml
├── lib/
│   └── my-local-lib-1.0.0.jar
└── src/

Important note

This works, but system scope is generally discouraged because:

• the dependency is not resolved like normal Maven dependencies
• it does not behave well in shared builds
• some tools and plugins may not handle it consistently

Option 2: Install the JAR into your local Maven repository

This is the preferred approach for local development.

Consider this setup:

mvn install:install-file \
  -Dfile=lib/my-local-lib-1.0.0.jar \
  -DgroupId=com.example \
  -DartifactId=my-local-lib \
  -Dversion=1.0.0 \
  -Dpackaging=jar

And this dependency:

<dependency>
  <groupId>com.example</groupId>
  <artifactId>my-local-lib</artifactId>
  <version>1.0.0</version>
</dependency>

What happens step by step:

1. Maven reads the install:install-file command.
2. It takes the physical file at lib/my-local-lib-1.0.0.jar.
3. It stores that file in your local Maven repository, usually under a path like:

~/.m2/repository/com/example/my-local-lib/1.0.0/

1. Maven associates that file with these coordinates:
   • groupId: com.example
   • artifactId:

Local JAR handling appears in several real situations:

• Internal company libraries not yet published to Artifactory, Nexus, or Maven Central
• Vendor SDKs distributed only as downloadable JAR files
• Legacy systems where dependencies are shared manually
• Prototype projects that depend on a library still under development
• Offline environments where developers cannot access remote repositories

Example scenarios:

• A payment hardware vendor gives your team terminal-sdk.jar
• A legacy reporting tool depends on old-report-engine.jar
• Another internal team sends you a test build of custom-auth-lib.jar

In each case, Maven still needs a way to identify and resolve that JAR consistently.

In real projects, developers usually avoid committing unmanaged JAR files directly unless there is no better option.

Common patterns include:

Installing once into the local repository

A developer runs:

mvn install:install-file -Dfile=vendor-sdk.jar -DgroupId=com.vendor -DartifactId=sdk -Dversion=2.1.0 -Dpackaging=jar

Then the project uses a normal dependency declaration.

Publishing to a private repository

In team environments, the better long-term solution is to publish the JAR to:

• Nexus
• Artifactory
• GitHub Packages
• an internal Maven repository

That way everyone gets the same dependency without manual setup.

Using guardrails in documentation

Teams often add setup instructions in:

• README.md
• onboarding docs
• build scripts

Example note:

Before building, install vendor-sdk-2.1.0.jar into your local Maven repository.

Validation and build consistency

Developers try to avoid hidden machine-specific paths such as:

<systemPath>C:/Users/Alice/Desktop/sdk.jar</systemPath>

These paths break on other machines.

1. Using an absolute file path

Broken example:

<systemPath>C:/Users/John/libs/tool.jar</systemPath>

Why it is a problem:

• only works on one machine
• breaks for teammates and CI

Safer version:

<systemPath>${project.basedir}/lib/tool.jar</systemPath>

Even better: install the JAR into the local Maven repository.

2. Forgetting system scope when using systemPath

Broken example:

<dependency>
  <groupId>com.example</groupId>
  <artifactId>tool</artifactId>
  <version>1.0</version>
  <systemPath>${project.basedir}/lib/tool.jar</systemPath>

system scope vs installed dependency

Quick reference

Direct local JAR reference

<dependency>
  <groupId>com.example</groupId>
  <artifactId>my-lib</artifactId>
  <version>1.0.0</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/lib/my-lib.jar</systemPath>
</dependency>

Install JAR into local Maven repository

mvn install:install-file \
  -Dfile=lib/my-lib.jar \
  -DgroupId=com.example \
  -DartifactId=my-lib \
  -Dversion=1.0.0 \
  -Dpackaging=jar

Normal dependency after installation

<dependency>
  <groupId>com.example</groupId>
  <artifactId>my-lib</artifactId>
  <version>1.0.0

Can I put a JAR inside my project and reference it directly in Maven?

Yes. You can use system scope with systemPath, but this is generally discouraged for long-term use.

What is the best way to use a local JAR in Maven?

Usually, install it into your local Maven repository with mvn install:install-file, then reference it like a normal dependency.

Why does Maven not recognize my local JAR automatically?

Maven resolves dependencies by coordinates and repositories, not by scanning random files in your project.

Will mvn install:install-file make the JAR available to my teammates?

No. It installs the JAR only on your machine. Teammates must install it too, or you should publish it to a shared repository.

Is system scope deprecated or discouraged?

It is widely discouraged in modern Maven usage because it bypasses normal dependency management.

Where does Maven store locally installed JAR files?

Usually in the local repository under ~/.m2/repository.

What if the local JAR changes?

You should reinstall the updated JAR and make sure the versioning stays clear and consistent.

• Maven dependencies — the core mechanism used to declare libraries in a project.
• Maven local repository — where Maven stores artifacts available on your machine.
• Maven scopes — helps explain what system scope means and why it behaves differently.
• Private artifact repositories — the proper team-level solution for sharing custom JAR files.
• Transitive dependencies — important because local JAR handling may not automatically manage dependent libraries.
• pom.xml — the file where Maven dependency configuration is declared.
• Build reproducibility — relevant because unmanaged local files often make builds inconsistent.