How to Create a Maven Project: Archetype, Directory Layout and IntelliJ IDEA

A command copied from an older tutorial, mvn archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 ..., finishes without errors, yet the very first build on JDK 21 fails with [ERROR] Source option 7 is no longer supported. Use 8 or later. Version 1.4 of the template wrote the maven.compiler.source and maven.compiler.target properties with the value 1.7 into pom.xml, and a modern javac no longer supports that version. A generated project is a starting point that needs checking, and this lesson shows exactly what to check.

Creating a Maven project means getting a directory with a pom.xml file (the project description and its coordinates groupId, artifactId and version) and the standard folder structure src/main/java, src/test/java and so on. There are three ways to do it: the mvn archetype:generate command based on a ready-made template (an archetype), the New Project wizard in IntelliJ IDEA, or manually by creating pom.xml and the directories yourself. The result is the same in every case: a project that builds with mvn package.

Ways to Create a Maven Project

You can create a Maven project with the mvn archetype:generate command (Maven must be installed), with the New Project wizard in IntelliJ IDEA (Maven is bundled with the IDE), or manually by writing pom.xml and creating the directories. For a simple console application all three give almost the same result; they differ in speed and in how much unnecessary content ends up in the project.

Installing Maven and checking the installation is covered in the lesson How to Install Maven on Windows, Linux and macOS. For the IDE-based methods a separate installation is not required.

What Is a Maven Archetype

A Maven archetype is a project template published in a repository as a regular artifact: it contains a draft pom.xml, directories and sample classes. The mvn archetype:generate command downloads the archetype and creates a new project from it, substituting your groupId, artifactId, version and package name.

Archetypes can be official (group org.apache.maven.archetypes) or third-party, published by framework authors. You can also create your own archetype for a company's typical projects. The best-known official archetypes are:

Spring Boot projects are usually created not with an archetype but with the start.spring.io generator (Spring Initializr): it also produces a regular Maven project with pom.xml and the same directory layout.

The mvn archetype:generate Command

The mvn archetype:generate command runs the generate goal of maven-archetype-plugin and creates a project in a subdirectory of the current folder (the subdirectory name equals the artifactId). It works in two modes: interactive, where it asks questions in the console, and batch, where all parameters are passed with -D in one command. Run it in a folder that does not contain a pom.xml yet.

Batch mode (recommended)

In batch mode (-DinteractiveMode=false) Maven asks nothing, so the command is easy to copy and repeat. Example for Linux, macOS and Git Bash:

mvn archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DgroupId=com.examclouds \
  -DartifactId=hello-maven \
  -Dversion=1.0-SNAPSHOT \
  -DinteractiveMode=false

On Windows the backslash does not work as a line continuation (in cmd it is ^, in PowerShell the backtick `), so it is easier to write the command on one line. In PowerShell, wrap every -D argument in quotes:

mvn archetype:generate "-DarchetypeGroupId=org.apache.maven.archetypes" "-DarchetypeArtifactId=maven-archetype-quickstart" "-DarchetypeVersion=1.5" "-DgroupId=com.examclouds" "-DartifactId=hello-maven" "-Dversion=1.0-SNAPSHOT" "-DinteractiveMode=false"

Output (fragment; the list of parameters depends on the archetype version):

[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.5
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.examclouds
[INFO] Parameter: artifactId, Value: hello-maven
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.examclouds
...
[INFO] Project created from Archetype in dir: /home/user/hello-maven
[INFO] BUILD SUCCESS

Command parameters:

Interactive mode

If you run mvn archetype:generate without parameters, Maven loads the archetype catalog and prints a long numbered list with the prompt Choose a number or apply filter. The default number points to maven-archetype-quickstart, but the numbers themselves change whenever the catalog is updated, so it is easier to type a filter such as quickstart. Maven then asks in turn for the archetype version, groupId, artifactId, version and package, and asks you to confirm the parameters (Y). Interactive mode is handy for exploring which archetypes exist; for a reproducible result use batch mode.

What quickstart generates and what to fix in pom.xml

The maven-archetype-quickstart archetype creates pom.xml, an App class whose main method prints Hello World!, and a stub test AppTest:

hello-maven/
├── pom.xml
└── src/
    ├── main/java/com/examclouds/App.java
    └── test/java/com/examclouds/AppTest.java

The content of pom.xml depends heavily on the archetype version. Versions up to and including 1.4 use JUnit 4 (the oldest ones even JUnit 3.8.1) and set the Java version with the pair maven.compiler.source/maven.compiler.target set to 1.7 - JDK 20 and newer no longer compile that. In version 1.5 the template moved to JUnit 5 (Jupiter) and the maven.compiler.release property. After generating the project, open pom.xml and check three things:

1. Java version. There should be a single maven.compiler.release property with your JDK version or lower (for example, 17 or 21). Replace the source/target pair with release - the reason is explained in the lesson What Is Maven.
2. JUnit version. If the dependencies contain junit:junit 3.x or 4.x and you write tests with JUnit 5, replace the dependency with org.junit.jupiter:junit-jupiter with scope = test and fix the imports in AppTest.
3. Encoding. The property project.build.sourceEncoding = UTF-8 - without it Maven warns about platform-dependent encoding, and builds on different operating systems may read non-ASCII strings differently.

The template's pluginManagement block with pinned plugin versions can stay: it makes the build reproducible. The meaning of each pom.xml tag is covered in a separate lesson of this module on the pom.xml file.

How to Choose groupId, artifactId and version

groupId is the organization or project group written as a reversed domain name (com.examclouds), artifactId is the project name in lowercase words separated by hyphens (hello-maven), and version is the version number; during development it gets the -SNAPSHOT suffix (1.0-SNAPSHOT). Together they form the project's GAV coordinates, by which it is found in a repository.

By default the archetype derives the Java package name from groupId, so the classes end up in com/examclouds/. If groupId contains a hyphen or a segment that starts with a digit, the generated package will not compile - set a valid -Dpackage explicitly. The artifactId and version form the name of the built file: hello-maven-1.0-SNAPSHOT.jar. How SNAPSHOT versions differ from releases when working with repositories is covered in the lesson on the pom.xml file in this module.

Maven Project Structure

A Maven project uses a fixed structure called the Standard Directory Layout: main code goes in src/main/java, resources in src/main/resources, tests in src/test/java and src/test/resources, and the build output appears in target. Maven knows these paths by default, so you do not declare them in pom.xml - you only need to put files in the right place.

hello-maven/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/examclouds/App.java
│   │   └── resources/
│   │       └── app.properties
│   └── test/
│       ├── java/
│       │   └── com/examclouds/AppTest.java
│       └── resources/
│           └── test-data.json
└── target/                 # created by Maven, do not commit
    ├── classes/
    ├── test-classes/
    └── hello-maven-1.0-SNAPSHOT.jar

Folders inside src/main/java mirror packages: the class com.examclouds.App lives in src/main/java/com/examclouds/App.java. Its test is conventionally placed in the same package under src/test/java - then the test can also access package-private members of the class.

What happens if a file is in the wrong place

Maven does not search the whole project for files: the compiler takes .java files only from the java directories, and resource copying works only from resources. A misplaced file often does not break the build; the problem shows up later, at runtime or in tests.

The standard paths can be overridden in pom.xml, but that is worth doing only when moving an old project to Maven that cannot be reorganized. The configuration is shown in the lesson on the pom.xml file in this module.

Maven Project in IntelliJ IDEA

To create a Maven project in IntelliJ IDEA, open the New Project wizard (File → New → Project), choose the Java generator with Maven as the build system or the Maven Archetype generator, and specify the name, location, JDK and GroupId/ArtifactId coordinates. The IDE creates pom.xml and the standard directories and imports the project immediately. You do not need to install Maven separately - it is bundled with the IDE.

The item names below match current versions of IntelliJ IDEA (Community and Ultimate); in older versions the wizard looks different, but the fields are the same.

New project: wizard fields

The Java generator with Build system = Maven usually produces a cleaner pom.xml than the old archetypes: the Java version in it comes from the selected JDK. Still, review the generated file against the checklist in the quickstart section.

The Maven tool window and syncing after editing pom.xml

The Maven tool window (usually on the right sidebar) shows the project as a tree: Lifecycle - build phases you run with a double-click (clean, compile, test, package...), Plugins - the configured plugins and their goals, Dependencies - the dependency tree.

IntelliJ IDEA does not re-read pom.xml on every keystroke. After you edit the file, a floating Load Maven Changes button appears in the editor (default shortcut Ctrl+Shift+O on Windows and Linux, Cmd+Shift+I on macOS). The Maven tool window has a Reload All Maven Projects button that does the same. Until the changes are loaded, a new dependency is highlighted in red in the code even though it is already in pom.xml.

Importing an existing project

An existing Maven project (for example, one cloned from Git) is opened with File → Open: select the pom.xml file and click Open as Project in the dialog (you can also select the folder that contains pom.xml). The IDE configures the source folders, JDK and dependencies on its own. If pom.xml sits in a subfolder and the IDE did not recognize it, right-click the file and choose Add as Maven Project.

Bundled Maven or your own: settings

Maven settings are under Settings (on macOS, Preferences) → Build, Execution, Deployment → Build Tools → Maven:

• Maven home path - Bundled (shipped with the IDE) or the path to your own installation. Point it to your installation if you need the same Maven version as in the terminal and on CI.
• User settings file and Local repository - paths to settings.xml and to the local repository (by default under ~/.m2); repository types are covered in a separate lesson of this module.
• The Runner subsection - the JDK that runs Maven and the Delegate IDE build/run actions to Maven option: with it, the Build and Run buttons go through Maven instead of the IDE's own builder.

If the project contains the Maven Wrapper, the IDE can use its Maven version - what mvnw is, is explained in the lesson What Is Maven.

Creating a Maven Project Manually

A Maven project can be created by hand in two minutes: a project directory containing pom.xml with the coordinates and Java version, plus the src/main/java and src/test/java folders with package subdirectories. The same approach is used to move existing code to Maven: sources go into src/main/java, and jar files from a lib folder are replaced with dependencies in pom.xml.

# Linux, macOS, Git Bash
mkdir -p hello-maven/src/main/java/com/examclouds hello-maven/src/main/resources hello-maven/src/test/java/com/examclouds

# Windows (PowerShell)
New-Item -ItemType Directory -Force hello-maven/src/main/java/com/examclouds, hello-maven/src/main/resources, hello-maven/src/test/java/com/examclouds

Put pom.xml into the hello-maven root - a minimal working version of about a dozen lines is shown in the lesson What Is Maven - and a class with a main method into src/main/java/com/examclouds:

package com.examclouds;

public class App {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

First Build and Run

Check the first build with three commands in the project root (where pom.xml is): mvn compile compiles the code into target/classes, mvn test also runs the tests, and mvn package builds a jar in target. Each command also runs the steps before it. The first run takes longer than usual because Maven downloads plugins into the local repository.

cd hello-maven
mvn test

Output (fragment for a quickstart project):

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.examclouds.AppTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
...
[INFO] BUILD SUCCESS

mvn package
java -cp target/hello-maven-1.0-SNAPSHOT.jar com.examclouds.App

Output:

[INFO] Building jar: /home/user/hello-maven/target/hello-maven-1.0-SNAPSHOT.jar
[INFO] BUILD SUCCESS
Hello World!

Note that running java -jar target/hello-maven-1.0-SNAPSHOT.jar fails with no main manifest attribute, in target/hello-maven-1.0-SNAPSHOT.jar - the archetype does not write the main class into the jar manifest. That is why the class is specified explicitly with -cp; adding Main-Class to the manifest via plugin configuration is covered in a separate lesson of this module on Maven plugins. If the project uses third-party libraries, they also have to be added to -cp - a regular jar does not contain them.

Why mvn package runs compilation and tests by itself, and how the phases differ, is covered in the lesson on the Maven build lifecycle in this module. How to run Java programs without Maven, with javac and java, is shown in the lesson Creating and Running a Java Application.

Where Beginners Get Tripped Up

Most problems with a first Maven project come down to where the command is run, which JDK Maven uses and which directory a file was put in. Below are the error messages and how to fix them.