Java Launcher Commands You Need to KnowThe Java launcher (commonly invoked with the java command) is the primary tool for running Java applications on the JVM. Whether you’re a beginner or an experienced developer, knowing the most useful Java launcher commands and options can speed up development, debugging, performance tuning, and deployment. This article explains essential java command options, practical examples, and tips so you can run Java programs confidently.
What the java launcher does
The java launcher starts a Java Virtual Machine (JVM) and runs Java bytecode. It locates and loads the necessary classes, sets up the runtime environment (classpath, module path), applies JVM options, and executes the specified main class or JAR. The launcher accepts both standard options (recognized by the Java specification) and JVM-specific options (often starting with -X or -XX) that control internal behavior.
Basic usage patterns
- Run a class by name:
java com.example.Main
- Run a JAR file with a Main-Class in its manifest:
java -jar myapp.jar
- Pass arguments to the Java program:
java com.example.Main arg1 arg2
Arguments after the class or -jar are handed to the Java program’s main method.
Essential options for everyday use
-
-classpath (or -cp): Specify where the launcher should look for classes and resources.
java -cp lib/*:classes com.example.Main
Use a colon (:) on macOS/Linux and a semicolon (;) on Windows.
-
-jar: Run an executable JAR file. When using -jar, the classpath and main class on the command line are ignored—use the JAR manifest for entry point and classpath.
java -jar myapp.jar
-
-version and –version: Print product version and exit.
java -version java --version
-
-showversion: Print version and continue to run the application.
-
-help and –help: Show usage help and exit.
java -help
Common JVM tuning options (-X and -XX)
-X and -XX options control runtime behavior and performance. Some are standardized across JVM implementations; others are HotSpot-specific.
-
Memory settings:
- -Xmx: Set maximum heap size.
java -Xmx2G com.example.Main
- -Xms: Set initial heap size.
java -Xms512m -Xmx2G com.example.Main
- -Xmx: Set maximum heap size.
-
Garbage collector selection and tuning (HotSpot examples):
- Use G1 GC:
java -XX:+UseG1GC -Xmx2G com.example.Main
- Use ZGC (on supported builds):
java -XX:+UseZGC -Xmx2G com.example.Main
- Use G1 GC:
-
Enable heap dumps on OutOfMemoryError:
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/heap.hprof com.example.Main
-
Print GC logs (modern syntax for Java 9+):
java -Xlog:gc*:file=gc.log:time,uptime,level -Xmx2G com.example.Main
Note: -XX options can differ between HotSpot and other JVMs; check your JVM documentation.
Debugging and diagnostic options
-
Remote debugging (JDWP) — allow a debugger to attach:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar myapp.jar
Set suspend=y to wait for the debugger before starting.
-
Enable assertions:
- Enable assertions for all classes:
java -ea com.example.Main
- Enable assertions for a specific package:
java -ea:com.example... com.example.Main
- Enable assertions for all classes:
-
JFR (Java Flight Recorder) for profiling (Java 11+ includes built-in JFR):
java -XX:StartFlightRecording=filename=recording.jfr,duration=60s,settings=profile -jar myapp.jar
-
Class and method tracing (for diagnostics):
java -verbose:class -verbose:gc com.example.Main
-verbose:class prints class loading events; -verbose:gc prints basic GC activity.
-
JMX (Java Management Extensions) remote access:
java -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -jar myapp.jar
For production systems, enable authentication and SSL.
Module system options (Java 9+)
If you use the Java Platform Module System (JPMS), these options help control modules:
-
–module-path (or -p): Specify module search path.
java --module-path mods --module com.example/com.example.Main
-
–add-modules: Add modules to the root set.
java --add-modules java.se.ee -jar myapp.jar
-
–add-opens and –add-exports: Open packages for reflection (useful when frameworks use reflection across module boundaries).
java --add-opens java.base/java.lang=ALL-UNNAMED -jar myapp.jar
Security options
- -Djava.security.manager (deprecated in newer releases but still present in older ones) enables the security manager.
- -Djava.security.policy=policyfile: Specify a security policy file.
- Use -D to set system properties:
java -Dconfig.file=app.conf -Dlog.level=DEBUG -jar myapp.jar
System properties are visible to the application via System.getProperty.
Running single-file source-code programs (Java 11+)
Java 11 introduced the ability to run a single Java source file without explicit compilation:
java Hello.java
This compiles and runs Hello.java in one step — handy for small scripts or examples.
Helpful examples and recipes
-
Run with explicit classpath and maximum heap:
java -cp "libs/*:target/classes" -Xms512m -Xmx1g com.example.Main
-
Run a Spring Boot fat JAR with remote debugging:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar
-
Start with G1 GC and GC logging to file:
java -XX:+UseG1GC -Xmx4G -Xlog:gc*:file=/var/log/myapp/gc.log:time,level -jar myapp.jar
-
Run a modular application:
java --module-path out/production --module com.example/com.example.Main
Tips and best practices
- Prefer configurations as environment variables or startup scripts (systemd, Docker ENTRYPOINT) instead of embedding options in code or packaging.
- Keep production JVM options under version control and document why each tuning flag exists.
- Use modern GC logging (-Xlog) on Java 9+ for structured, timestamped GC output.
- Test GC and heap settings with realistic load and profiling tools (JFR, async-profiler) rather than relying solely on heuristics.
- For containerized environments, set -Xmx to a value that considers container limits; also consider JVM container-awareness flags (modern JDKs auto-detect container limits).
Troubleshooting common issues
- “Could not find or load main class” — check class name, package, and classpath.
- Wrong manifest or -jar misuse — remember -jar ignores the command line classpath.
- OutOfMemoryError — increase heap (-Xmx) or analyze memory with heap dump and profiler.
- Native memory exhaustion — check thread stack size (-Xss), direct buffer allocations, and native libraries.
Conclusion
Knowing the key java launcher commands gives you control over how the JVM runs your applications: setting classpaths, tuning memory and garbage collection, enabling diagnostics and debugging, and using the module system. Use the examples and best practices above to build reliable, observable, and well-tuned Java applications.