Build Java Projects Offline: A Practical Guide to Using Maven Local Repository on Windows

Introduction

In many enterprise and corporate environments, Java developers don’t always have the luxury of unrestricted internet access. Firewalls, security policies, or isolated build servers can prevent Maven from downloading dependencies directly from public repositories like Maven Central. When that happens, even a simple mvn clean install can fail and bring development to a halt.

Fortunately, Maven is designed to work just as well in offline and restricted environments—if you know how to use its local repository correctly. By manually downloading required JAR files and installing them into a local Maven repository, you can continue building and running Java projects without relying on an internet connection.

In this article, you’ll learn how to build Java projects completely offline on Windows using Maven’s local repository. We’ll walk through creating a simple Maven project, manually installing dependencies, enabling offline mode, and building the application using VS Code as the editor. By the end, you’ll have a practical, repeatable approach that works perfectly behind firewalls, on secured machines, or in air-gapped environments.

Prerequisites

Make sure you have the following installed:

• Java JDK 8+
• Apache Maven
• VS Code
• Java Extension Pack for VS Code

Verify installation:

java -version
mvn -version

Step 1: Understand Maven Local Repository

By default, Maven stores dependencies in:

C:\Users\<your-username>\.m2\repository

This is called the local repository. When you run:

mvn clean install

Maven:

• Checks the local repository
• If missing, downloads from the internet
• Saves it locally

👉 Our goal is to skip step 2 and work offline only.

Step 2: Create a Simple Maven Project

• Open VS Code
• Type Ctrl + Shift + P to open Command Palette
• Type Maven: Create Maven Project
• Select ‘No Archetype’ and follow prompts to create a basic project
• In my case - groupId: com.mahedee, artifactId: offline-demo

Step 3: Choose a Library (Example: Apache Commons Lang)

We will use Apache Commons Lang. The purpose of us using this library is to convert a string to upper case.

Normally, you would add this dependency:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
</dependency>

But instead of letting Maven download it, we will do it manually.

Step 4: Download Required Dependencies Manually

Since we’re working offline, we need to manually download all required JAR files and POM files. Here’s the complete list:

Primary dependency:

1. commons-lang3-3.14.0.jar
   • URL: https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar
   • Save to: C:\Users\mahedee\Downloads\commons-lang3-3.14.0.jar

Required dependencies and POMs:

1. maven-shared-utils-3.3.4.jar
   • URL: https://repo1.maven.org/maven2/org/apache/maven/shared/maven-shared-utils/3.3.4/maven-shared-utils-3.3.4.jar
   • Save to: C:\Users\mahedee\Downloads\maven-shared-utils-3.3.4.jar
2. commons-io-2.6.jar
   • URL: https://repo1.maven.org/maven2/commons-io/commons-io/2.6/commons-io-2.6.jar
   • Save to: C:\Users\mahedee\Downloads\commons-io-2.6.jar
3. commons-io-2.6.pom
   • URL: https://repo1.maven.org/maven2/commons-io/commons-io/2.6/commons-io-2.6.pom
   • Save to: C:\Users\mahedee\Downloads\commons-io-2.6.pom
4. maven-shared-components-34.pom
   • URL: https://repo1.maven.org/maven2/org/apache/maven/shared/maven-shared-components/34/maven-shared-components-34.pom
   • Save to: C:\Users\mahedee\Downloads\maven-shared-components-34.pom
5. commons-parent-42.pom
   • URL: https://repo1.maven.org/maven2/org/apache/commons/commons-parent/42/commons-parent-42.pom
   • Save to: C:\Users\mahedee\Downloads\commons-parent-42.pom
6. apache-18.pom
   • URL: https://repo1.maven.org/maven2/org/apache/apache/18/apache-18.pom
   • Save to: C:\Users\mahedee\Downloads\apache-18.pom

💡 Pro Tip: Create a C:\temp\offline-jars folder to organize all downloaded files in one place.

Step 5: Install Dependencies into Local Maven Repository

Setup offline repository:

1. Create an offline repository folder:

   mkdir C:\Users\%USERNAME%\.m2\offline-repository
   

2. Open PowerShell in your project directory (where pom.xml is located)

Install all dependencies systematically:

# Install commons-lang3 JAR
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\commons-lang3-3.14.0.jar" "-DgroupId=org.apache.commons" "-DartifactId=commons-lang3" "-Dversion=3.14.0" "-Dpackaging=jar" "-DlocalRepositoryPath=C:\Users\mahedee\.m2\offline-repository"

# Install maven-shared-utils JAR
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\maven-shared-utils-3.3.4.jar" "-DgroupId=org.apache.maven.shared" "-DartifactId=maven-shared-utils" "-Dversion=3.3.4" "-Dpackaging=jar" "-DlocalRepositoryPath=C:\Users\mahedee\.m2\offline-repository"

# Install commons-io JAR
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\commons-io-2.6.jar" "-DgroupId=commons-io" "-DartifactId=commons-io" "-Dversion=2.6" "-Dpackaging=jar" "-DlocalRepositoryPath=C:\Users\%USERNAME%\.m2\offline-repository"

# Install commons-io POM
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\commons-io-2.6.pom" "-DgroupId=commons-io" "-DartifactId=commons-io" "-Dversion=2.6" "-Dpackaging=pom" "-DlocalRepositoryPath=C:\Users\%USERNAME%\.m2\offline-repository"

# Install maven-shared-components POM
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\maven-shared-components-34.pom" "-DgroupId=org.apache.maven.shared" "-DartifactId=maven-shared-components" "-Dversion=34" "-Dpackaging=pom" "-Dmaven.repo.local=C:\Users\mahedee\.m2\offline-repository"

# Install commons-parent POM
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\commons-parent-42.pom" "-DgroupId=org.apache.commons" "-DartifactId=commons-parent" "-Dversion=42" "-Dpackaging=pom" "-DlocalRepositoryPath=C:\Users\%USERNAME%\.m2\offline-repository"

# Install apache POM
mvn install:install-file "-Dfile=C:\Users\mahedee\Downloads\apache-18.pom" "-DgroupId=org.apache" "-DartifactId=apache" "-Dversion=18" "-Dpackaging=pom" "-DlocalRepositoryPath=C:\Users\%USERNAME%\.m2\offline-repository"

💡 Alternative approach:

• Download and install all dependencies for your project offline:
  • Navigate to the directory where your pom.xml file is located, then run the following command in your terminal or PowerShell:

mvn dependency:go-offline "-Dmaven.repo.local=C:\Users\mahedee\.m2\offline-repository" 

Verify installation:

• Navigate to C:\Users\%USERNAME%\.m2\offline-repository
• Confirm that the dependency folders are created with proper Maven directory structure
• You should see folders like org/apache/commons/commons-lang3/3.14.0/

Step 6: Configure Maven to Use the Offline Repository

• Open or create settings.xml in C:\Users\<your-username>\.m2\
• Add the following configuration:

<settings>
  <localRepository>C:\Users\<your-username>\.m2\offline-repository</localRepository>
</settings>

Example:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <!-- Local repository location -->
  <localRepository>C:\Users\mahedee\.m2\offline-repository</localRepository>
</settings>

Step 7: Add Dependency to pom.xml

• Open pom.xml in your Maven project
• Add the dependency for commons-lang3:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
</dependency>

Step 8: Use the Library in Code

Edit Main.java:

package com.mahedee;

import org.apache.commons.lang3.StringUtils;

public class Main {
    public static void main(String[] args) {
        String text = "Hello Maven Offline World";
        System.out.println(StringUtils.upperCase(text));
    }
}

Step 9: Build the Project in Offline Mode

Now disconnect from the internet (optional but recommended 😄).

Run:

mvn clean package -o

Important flag:

• -o → offline mode

If everything is correct, Maven will:

• Use only the local repository
• Not try to download anything
• Build successfully 🎉

Step 10: Run the Application

• Now run the application using and see the output:

HELLO MAVEN OFFLINE WORLD

Step 11: (Optional) Configure Maven to Always Use Local Repo

You can enforce offline usage via settings.xml.

Create or edit:

C:\Users\<your-username>\.m2\settings.xml

<settings>
    <offline>true</offline>
</settings>

⚠️ Use this carefully—Maven will never download dependencies.

Conclusion Building Java projects offline using Maven’s local repository on Windows is entirely feasible with the right approach. By manually downloading and installing necessary JAR files, configuring Maven to use a local repository, and leveraging offline mode, you can maintain productivity even in restricted environments. If this guide helped you, consider sharing it with your developer peers who might face similar challenges.

Happy coding! 🚀