rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat jmod.md

jmod — the JMOD format and tool

# Link-time packaging format for modules that can carry native libraries and config, consumed by jlink but never shipped to run.

Conceptsaved 2026-08-09 #java#jvm#tooling#modules#packaging

Overview

JMOD is a packaging format (and the jmod tool that creates/inspects it) introduced alongside the module system in Java 9. It exists because jars cannot cleanly carry everything a module may need at link time: native libraries, header files, config files, man pages and legal notices. The JDK itself ships as a set of .jmod files under $JAVA_HOME/jmods, which is exactly what jlink consumes to build runtime images.

Key points

  • Beyond the jar: a jmod holds classes plus sectioned content — lib/ (native libraries), include/ (headers), conf/ (configuration), bin/, man/, legal/. A jar can only smuggle natives inside the archive and extract them at runtime; a jmod places them properly on link.
  • Link-time only: jmods are input to jlink (and to javac/jmod module paths). The Java launcher cannot execute a jmod, and there is no runtime jmod loading — which is why you never ship jmods to end users; you ship a jlinked runtime or a jar.
  • Format: essentially a zip with a small magic header — not the jimage format that jlink produces (lib/modules), and not interchangeable with it.
  • Tool verbs: jmod create (with --class-path, --libs, --cmds, --config), jmod list (entries), jmod describe (module descriptor), jmod extract, jmod hash (records hashes of tied modules for integrity checking).
  • When you'd make one: mainly if you distribute a library with native components intended to be jlinked into runtimes (e.g. a JNI/FFM-backed library); everyday applications stick with modular jars, which jlink also accepts.
  • Cross-platform linking: because jmods carry per-platform natives, downloading another platform's JDK jmods lets jlink cross-build runtime images for that platform.

Examples

jmod create --class-path build/classes \
     --libs build/natives \
     --module-version 1.2.0 \
     mylib.jmod
jmod describe $JAVA_HOME/jmods/java.sql.jmod

Related

  • JDK & tools — parent catalogue of the JDK toolchain.
  • jlink — the sole consumer of jmods, at runtime-image link time.
  • jar tool — the run-time packaging format jmod deliberately does not replace.
  • jpackage — downstream: turns the linked runtime into an installer.
  • Build ecosystem — artefact formats (jar, jmod, image) in the build pipeline.