MapStruct generates plain-Java bean mappers at compile time, so mapping gaps are reported at build time

An interface with one annotation becomes a class of plain method calls at compile time

MapStruct is a Java annotation processor. You declare a mapper interface, and the build writes its implementation. The README's example maps a car to a DTO:

@Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );

    @Mapping(target = "seatCount", source = "numberOfSeats")
    CarDto carToCarDto(Car car);
}

At compile time, the generated implementation uses plain Java method invocations to copy values between source and target objects, so no reflection is involved. Properties are mapped by default when they have the same name on both sides, and `@Mapping` plus a handful of other annotations override that rule. In the example, `numberOfSeats` is renamed to `seatCount`.

Support covers conventional beans and Java 16+ records. The practical effect is that the mapping logic exists as ordinary source you can open, step through in a debugger, or edit by hand if the generator has a bug, which is one of the advantages the README lists.

Incomplete and incorrect mappings stop the build instead of failing at runtime

The README contrasts MapStruct with mapping frameworks that work at runtime. The central contrast is when errors appear. MapStruct reports two kinds of problem at build time: mappings that are incomplete, where not all target properties are mapped, and mappings that are incorrect, where no proper mapping method or type conversion can be found.

Type safety follows from the same design. Only objects and attributes that map to each other can be mapped, so an order entity cannot be accidentally mapped into a customer DTO.

The consequence is a different team habit. A new field added to a target class is reported at build time as an incomplete mapping. The README says generated code has no runtime dependencies, so what you ship is the generated classes plus the small annotation artifact. It does not describe how to tell the processor to ignore unmapped targets, and for that it sends you to the reference guide.

Maven needs the dependency and a compiler plugin that can run the processor

For Maven, the README adds a version property and the dependency, with artifacts coming from Maven Central:

<properties>
    <org.mapstruct.version>1.6.3</org.mapstruct.version>
</properties>
...
<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${org.mapstruct.version}</version>
    </dependency>
</dependencies>

It also shows `maven-compiler-plugin` version 3.13.0 with source and target set to 17, but the snippet in the README stops there. The annotation processor path configuration is not visible in the text, so copy the full Maven section from the README or from the reference guide before relying on it.

The mismatch is worth catching. The Requirements section says MapStruct requires Java 1.8 or later, while the Maven example compiles for 17. Both can be true, since the example is a sample setup, but do not copy the 17 into a Java 8 project. The README also notes a distribution bundle on the Releases page for builds that use no dependency management tool.

Gradle declares the processor separately for main and test code

The Gradle sketch separates the runtime annotation artifact from the processor:

plugins {
    ...
    id "com.diffplug.eclipse.apt" version "3.26.0" // Only for Eclipse
}

dependencies {
    ...
    implementation 'org.mapstruct:mapstruct:1.6.3'

    annotationProcessor 'org.mapstruct:mapstruct-processor:1.6.3'
    testAnnotationProcessor 'org.mapstruct:mapstruct-processor:1.6.3' // if you are using mapstruct in test code
}
...

The `implementation` line brings in `org.mapstruct:mapstruct`, the annotations. The `annotationProcessor` line brings in `org.mapstruct:mapstruct-processor`, which does the generation. A mistake here is quiet: with only the first line, the code compiles, the interface exists, and no implementation class is generated, so `Mappers.getMapper` fails when it runs.

Test code needs its own `testAnnotationProcessor` line, and the README flags it as needed only if you use MapStruct in tests. The `com.diffplug.eclipse.apt` plugin line is marked as only for Eclipse, so an IntelliJ or command-line build can leave it out.

IDE support is a plug-in for IntelliJ and an Eclipse plug-in still in development

MapStruct works in command line builds (plain javac, Maven, Gradle, Ant and others) and in IDEs. For IntelliJ, a plug-in is available in the marketplace as MapStruct Support. For Eclipse, the dedicated plug-in is described as in development, at github.com/mapstruct/mapstruct-eclipse, and goes beyond what an annotation processor can do by adding content assist for annotation attributes and quick fixes.

For importing MapStruct itself into Eclipse, the README asks for the m2e_apt plugin. In IntelliJ, annotation processing has to be enabled under Build, Execution, Deployment, then Compiler, then Annotation Processors, and the README asks for at least IntelliJ 2018.2.x because support for `annotationProcessors` from the `maven-compiler-plugin` begins with that version.

The failure mode is a mapper that compiles in Maven but shows missing-class errors in the editor. The README attributes IDE trouble to annotation processing being switched off. That instruction appears under the heading about importing MapStruct itself into an IDE, so it applies to contributors, and users should treat it as a hint rather than a rule.

Building MapStruct needs Java 21, although using it needs Java 1.8

Using the library and building it are different demands. The Requirements section says Java 1.8 or later for MapStruct as a dependency. The Building from Source section says Java 21 is required to build MapStruct itself, and the build uses Maven through the wrapper:

./mvnw clean install

To skip the distribution module:

./mvnw clean install -DskipDistribution=true

The repository is organized into modules: `core/`, `core-jdk8/`, `processor/`, `distribution/`, `documentation/`, `integrationtest/` and `parent/`, with `build-config/` alongside. A contributor changing generator behavior will work in `processor/`, while `core-jdk8/` suggests a separate artifact for the older runtime, though the README does not explain it.

MapStruct uses the gem annotation processor to generate mapping gems for its own annotations. That is why a contributor's IDE has to have annotation processing enabled, or the project's own annotations will not resolve.

The README pins 1.6.3 while the newest tags are 1.7.0 betas, and the license field says NOASSERTION

Every MapStruct version number in the README is 1.6.3, including the badge links and the Maven and Gradle snippets. That release is dated 2024-11-09. Newer tags exist: 1.7.0.Beta1 on 2026-02-01 and 1.7.0.Beta2 on 2026-06-27. There is also a `NEXT_RELEASE_CHANGELOG.md` at the top level. The repository is not archived, and its last push was on 2026-10-16.

For a production project, the stable line in the README is 1.6.3, and moving to 1.7.0.Beta2 is a choice to accept pre-release behavior. The README does not list what changed in the betas.

The repository's license field reads NOASSERTION, but the README's Licensing section states the Apache License, Version 2.0, and a `LICENSE.txt` is in the tree. So the project's own text answers the question that the automatic detection could not.

Help goes through GitHub Discussions, and the Links list adds an issue tracker and a user group.

Editorial conclusion

MapStruct suits Java teams that want entity-to-DTO mapping checked at build time and readable generated code instead of reflection. It does not help if your build cannot run an annotation processor, which is the one thing to verify first. Pin a stable version deliberately: the README example uses 1.6.3, and the newer 1.7.0 releases are betas.

Frequently asked questions

Official sources

1. Issues
2. mapstruct/mapstruct on GitHub
3. Project website
4. README
5. Releases