Module Import Declarations in Java 25 (JEP 511): import module java.base

Versions. Tested on JDK 25.0.4.1 (Temurin, LTS) and JDK 27+35 (Temurin, GA 15 September 2026). JDK 21 appears only for the “before” transcripts. JEP 511 is final in 25: no --enable-preview. Compiling this syntax with --release 24 or lower is rejected (the exact message is in the accordion at the end of the first section). openjdk.org/jeps returned HTTP 403 to the tooling used for this article, so behaviour below comes from javac, java and the Java Language Specification, section 7.5.5, not from the JEP text.

One line instead of seven: what import module does

import java.nio.file.Path;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class OldWay {
    public static void main(String[] args) {
        List<String> words = List.of("apple", "avocado", "banana", "blueberry", "cherry");
        Map<Character, List<String>> byInitial = words.stream()
                .collect(Collectors.groupingBy(w -> w.charAt(0)));
        System.out.println(byInitial);
        System.out.println(Path.of("a", "b", "c.txt") + " on " + LocalDate.of(2026, 9, 15));
    }
}

import module java.base;

$ javac src/OldWay.java && java OldWay     (25.0.4.1+1-LTS)
{a=[apple, avocado], b=[banana, blueberry], c=[cherry]}
a/b/c.txt on 2026-09-15

$ javac src/NewWay.java && java NewWay     (27+35)
{a=[apple, avocado], b=[banana, blueberry], c=[cherry]}
a/b/c.txt on 2026-09-15

$ cmp OldWay.class NewWay.class     (javac -g:none; NewWay renamed to OldWay inside the class file)
identical, byte for byte (2249 bytes)

It is a compile-time convenience, nothing more. The module import does not add the module to your program’s dependencies, does not put anything on a path, and does not make a class loadable that was not loadable before. It only widens the set of simple names the compiler will accept. Everything about readability (which modules your code may use at all) still comes from where you run it, which is what the rest of this article is about.

$ javac broken/NoSuchModule.java     (25.0.4.1+1-LTS)
broken/NoSuchModule.java:1: error: imported module not found: java.nosuch
import module java.nosuch;
^
1 error

$ javac broken/ModuleInsideClass.java     (25.0.4.1+1-LTS)
broken/ModuleInsideClass.java:2: error: illegal start of type
    import module java.base;
    ^
broken/ModuleInsideClass.java:2: error: ';' expected
    import module java.base;
                      ^
broken/ModuleInsideClass.java:2: error: <identifier> expected
    import module java.base;
                           ^
3 errors

$ javac --release 24 src/NewWay.java     (25.0.4.1+1-LTS)
src/NewWay.java:1: error: module imports are not supported in -source 24
import module java.base;
       ^
  (use -source 25 or higher to enable module imports)
1 error
exit=1

$ javac src/NewWay.java     (21.0.10+7-Ubuntu-124.04)
src/NewWay.java:1: error: '.' expected
import module java.base;
             ^
1 error

Going deeper on this section

• Companion repo: jep511 README (how to regenerate every transcript)
• Official reference: JLS 7.5.5, Single-Module-Import Declarations
• Official reference: JEP 511: Module Import Declarations
• Related on this site: Compact Source Files and Instance Main Methods in Java 25 (JEP 512) — the other Java 25 change that removes ceremony from the first lines of a file

When two modules export the same name: the ambiguity error

import module java.base;
import module java.sql;

public class AmbiguousDate {
    public static void main(String[] args) {
        Date d = new Date(0L);
        System.out.println(d);
    }
}

$ javac broken/AmbiguousDate.java     (25.0.4.1+1-LTS)
broken/AmbiguousDate.java:6: error: reference to Date is ambiguous
        Date d = new Date(0L);
        ^
  both class java.sql.Date in java.sql and class java.util.Date in java.util match
broken/AmbiguousDate.java:6: error: reference to Date is ambiguous
        Date d = new Date(0L);
                     ^
  both class java.sql.Date in java.sql and class java.util.Date in java.util match
2 errors

$ javac broken/AmbiguousList.java     (25.0.4.1+1-LTS)
broken/AmbiguousList.java:6: error: reference to List is ambiguous
        List<String> names = new ArrayList<>();
        ^
  both class java.awt.List in java.awt and interface java.util.List in java.util match
1 error

import module java.base;
import module java.sql;
import java.util.Date;          // a single-type import wins over both module imports

public class FixedDate {
    public static void main(String[] args) {
        Date d = new Date(0L);
        System.out.println(d.getClass().getName());
        java.sql.Date s = new java.sql.Date(0L);   // the other one is still reachable by its full name
        System.out.println(s.getClass().getName());
    }
}

$ javac src/FixedDate.java && java FixedDate     (25.0.4.1+1-LTS)
java.util.Date
java.sql.Date

An ambiguity is only an error where the name is used. UnusedAmbiguity.java imports java.base and java.sql and never mentions Date; it compiles and runs, on 25 and 27 alike (see 03-precedence.txt). That has a consequence for later: you can add a second module import to a working file and nothing complains until the first line that uses a clashing name.

Going deeper on this section

• Companion repo: broken/ (the sources that must fail) and run.sh
• Official reference: JLS 6.4.1, Shadowing (my table above is observed behaviour; the JLS gives the general rule)
• Related on this site: JEP 512 post, where a compact source file gets java.base imported implicitly and shows the same clashes

What one module import actually brings in (and what it leaves out)

$ java --describe-module java.sql     (25.0.4.1+1-LTS)
[email protected]
exports java.sql
exports javax.sql
requires java.transaction.xa transitive
requires java.base mandated
requires java.xml transitive
requires java.logging transitive
uses java.sql.Driver

import module java.base;
import module java.sql;

public class Transitive {
    public static void main(String[] args) {
        // java.sql declares "requires transitive" java.logging, java.xml and java.transaction.xa,
        // so importing java.sql also imports their exported packages.
        Logger log = Logger.getLogger("demo");                     // java.util.logging   (java.logging)
        System.out.println(log.getName());
        System.out.println(XAResource.TMNOFLAGS);                  // javax.transaction.xa (java.transaction.xa)
        System.out.println(DocumentBuilderFactory.class.getModule().getName());  // javax.xml.parsers (java.xml)
        List<String> l = List.of("java.base needed its own import");
        System.out.println(l);
    }
}

$ javac src/Transitive.java && java Transitive     (25.0.4.1+1-LTS)
demo
0
java.xml
[java.base needed its own import]

$ javac broken/SqlDoesNotGiveBase.java     (25.0.4.1+1-LTS)
broken/SqlDoesNotGiveBase.java:5: error: cannot find symbol
        List<String> l = List.of("x");     // java.util.List lives in java.base
        ^
  symbol:   class List
  location: class SqlDoesNotGiveBase
broken/SqlDoesNotGiveBase.java:5: error: cannot find symbol
        List<String> l = List.of("x");     // java.util.List lives in java.base
                         ^
  symbol:   variable List
  location: class SqlDoesNotGiveBase
2 errors

$ java --describe-module java.se | grep -c exports     (25.0.4.1+1-LTS)
0

$ javac src/JavaSe.java     (25.0.4.1+1-LTS)
src/JavaSe.java:1: error: unnamed module does not read: java.se
import module java.se;
^
1 error

$ javac --add-modules java.se src/JavaSe.java && java JavaSe     (25.0.4.1+1-LTS)
[a] x 0

import module java.se; is a very wide net. It pulls in twenty modules, including java.desktop, java.sql and java.xml. Every well-known simple name that appears in more than one of them becomes ambiguous the moment you use it. It is fine for a throwaway script, and a poor habit for anything a colleague will read.

Going deeper on this section

• Companion repo: output/04 has the full --describe-module output and both JDKs’ runs
• Official reference: java.se module summary (the API documentation for the umbrella module)
• Official reference: JLS 7.3, Compilation Units (which modules a compilation unit reads)

Packages, module-info.java and libraries

package demo.mod;

import module java.base;

public class InPackage {
    public static void main(String[] args) {
        System.out.println(List.of(1, 2, 3) + " from package " + InPackage.class.getPackageName());
    }
}

$ javac src/InPackage.java && java demo.mod.InPackage     (25.0.4.1+1-LTS)
[1, 2, 3] from package demo.mod

module demo.noreq { }

package demo;

import module java.sql;       // demo.noreq never says "requires java.sql"

public class NoReq {
    public static void main(String[] args) {
        System.out.println(Connection.TRANSACTION_NONE);
    }
}

$ javac -d out --module-source-path multi --module demo.noreq     (25.0.4.1+1-LTS)
multi/demo.noreq/demo/NoReq.java:3: error: module demo.noreq does not read: java.sql
import module java.sql;       // demo.noreq never says "requires java.sql"
^
1 error

module acme.text {
    exports acme.text;          // acme.text.internal is NOT exported
}

package demo;

import module acme.text;     // imports Slug, but not acme.text.internal.Helper

public class App {
    public static void main(String[] args) {
        System.out.println(Slug.of("Import Module: Hello, World!"));
    }
}

$ javac -d out --module-source-path multi --module acme.text,demo.app && java -p out -m demo.app/demo.App     (25.0.4.1+1-LTS)
import-module-hello-world

$ javac -p lib src/ThirdParty.java     (25.0.4.1+1-LTS)
src/ThirdParty.java:1: error: unnamed module does not read: acme.text
import module acme.text;
^
1 error

$ javac -p lib --add-modules acme.text src/ThirdParty.java && java -p lib --add-modules acme.text -cp out ThirdParty     (25.0.4.1+1-LTS)
a-script-using-a-library-module

Going deeper on this section

• Companion repo: multi/ (the three modules and the deliberate failures)
• Official reference: javac command reference (--module-source-path, --add-modules)
• Related on this site: Flexible Constructor Bodies in Java 25 (JEP 513), the same series, which uses the same run.sh + transcript layout

Scripts, compact source files and jshell: where it earns its keep

void main() {
    IO.println(List.of("no imports at all"));
}

public class ClassicNoImport {
    public static void main(String[] args) {
        System.out.println(List.of("no imports at all"));
    }
}

$ javac src/CompactNoImport.java && java CompactNoImport     (25.0.4.1+1-LTS)
[no imports at all]

$ javac broken/ClassicNoImport.java     (25.0.4.1+1-LTS)
broken/ClassicNoImport.java:3: error: cannot find symbol
        System.out.println(List.of("no imports at all"));
                           ^
  symbol:   variable List
  location: class ClassicNoImport
1 error

import module java.sql;

void main() {
    var l = List.of("java.base came implicitly");      // no import module java.base written
    IO.println(l + " " + Connection.TRANSACTION_NONE);  // java.sql from the explicit import
}

$ javac src/CompactPlusImport.java && java CompactPlusImport     (25.0.4.1+1-LTS)
[java.base came implicitly] 0

import module java.base;

void main() {
    var now = LocalDate.of(2026, 9, 15);
    IO.println(Stream.of("a", "b", "c").collect(Collectors.joining("-")) + " " + now);
}

$ java src/Script.java     (25.0.4.1+1-LTS)
a-b-c 2026-09-15

$ jshell --feedback concise src/imports.jsh     (21.0.10+7-Ubuntu-124.04)
  import java.io.*
  import java.math.*
  import java.net.*
  import java.nio.file.*
  import java.util.*
  import java.util.concurrent.*
  import java.util.function.*
  import java.util.prefs.*
  import java.util.regex.*
  import java.util.stream.*
[2, 4]
Error:
cannot find symbol
  symbol:   variable LocalDate
System.out.println(LocalDate.of(2026, 9, 15))
                   ^-------^

$ jshell --feedback concise src/imports.jsh     (25.0.4.1+1-LTS)
  import java.base
[2, 4]
2026-09-15

Scripts and teaching: yes. A large codebase: decide as a team. The feature costs nothing at runtime and removes a real barrier for a beginner. In a long-lived application it trades an explicit list (which shows a reviewer exactly what the file depends on) for a shorter one. The two downsides I can back up from these tests are the ambiguity errors that appear as soon as two module imports overlap, and that the file stops compiling below Java 25. What I did not test is how IDEs, formatters, import-organising plugins, Maven and Gradle treat the syntax; check those on your toolchain before you adopt it across a team.

$ diff <(javap -c -p -l OldWay) <(javap -c -p -l NewWay)     (default javac -g keeps line numbers)
8c8
<         line 9: 0
---
>         line 3: 0
52,57c52,57
<         line 11: 0
<         line 12: 14
<         line 13: 25
<         line 14: 37
<         line 15: 44
<         line 16: 90
---
>         line 5: 0
>         line 6: 14
>         line 7: 25
>         line 8: 37
>         line 9: 44
>         line 10: 90
67c67
<         line 13: 0
---
>         line 7: 0

Going deeper on this section

• Companion repo: src/ (every runnable example in this article)
• Official reference: jshell command reference
• Related on this site: Compact Source Files and Instance Main Methods in Java 25 (JEP 512)

Should you use this?

What I did not test. I did not test the earlier preview versions of this feature (which is why I say nothing about JDK 23 or 24 behaviour), any tool outside the JDK (IDEs, Maven, Gradle, formatters), or what happens when a future JDK adds a class to an existing module that clashes with a name you already use. That last case follows from how on-demand imports work, but I have not seen it happen, so treat it as a reasoned risk and not an observation.

Further reading

• Companion repository for this article: javademos, jep511 module
• Official reference: JEP 511: Module Import Declarations
• Official reference: JLS 7.5.5, Single-Module-Import Declarations (Java SE 25)
• Related on this site: Compact Source Files and Instance Main Methods in Java 25 (JEP 512)
• Related on this site: Flexible Constructor Bodies in Java 25 (JEP 513): Validate Before super()
• Related on this site: Java 27 Is Out: Every JEP, Plus the Java 26 Changes You Skipped