Command Line Options

This document describes the most useful command line options of the VisualVM launcher.

Use visualvm --help for a complete list of all available options.

On this page:

• Setup Options
• Appearance Options
• Functional Options
• System Properties

---

Setup Options

• --jdkhome Sets the JDK installation to run VisualVM.
• Typically VisualVM finds and uses a compatible JDK automatically. Use the --jdkhome option only if needed.
• Usage:
  visualvm --jdkhome <path_to_jdk>
• Example:
  visualvm --jdkhome "C:\Program Files\Java\jdk11" (Windows)
  visualvm --jdkhome /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home (macOS)
  visualvm --jdkhome /usr/java/jdk11 (Linux)

• --userdir Defines the directory to store user settings like remote hosts, JMX connections, etc., and installed plugins.
• VisualVM starts with a default user directory without any configuration. Use the --userdir option only if needed.
• Default user directory:
  C:\Users\<user>\AppData\Roaming\VisualVM\<version> (Windows)
  /Users/<user>/Library/Application Support/VisualVM/<version> (macOS)
  /home/<user>/.visualvm/<version> (Linux)
• Usage:
  visualvm --userdir <path_to_userdir>
• Example:
  visualvm --userdir C:\Users\Me\visualvm_userdir (Windows)
  visualvm --userdir /home/me/visualvm_userdir (macOS, Linux)

• --cachedir Defines the directory to store user cache, must be different from userdir.
• VisualVM starts with a default cache directory without any configuration. Use the --cachedir option only if needed.
• Default cache directory:
  C:\Users\<user>\AppData\Local\VisualVM\Cache\<version> (Windows)
  /Users/<user>/Library/Caches/VisualVM/<version> (macOS)
  /home/<user>/.cache/visualvm/<version> (Linux)
• Usage:
  visualvm --cachedir <path_to_userdir>
• Example:
  visualvm --cachedir C:\Users\Me\visualvm_cachedir (Windows)
  visualvm --cachedir /home/me/visualvm_cachedir (macOS, Linux)

• --cp:p and --cp:a Prepends or appends custom classpath to the VisualVM classpath.
• Usage:
  visualvm --cp:p <custom_classpath>
visualvm --cp:a <custom_classpath>
• Example:
  visualvm --laf com.my.LookAndFeel --cp:a %TEMP%\mylookandfeel.jar

Appearance Options

• --laf Defines the Swing look and feel used to render the VisualVM GUI.
• Usage:
  visualvm --laf <LaF_name> where LaF_name is one of Metal | Windows | Aqua | GTK
  visualvm --laf <LaF_classname> where LaF_classname is the custom LaF classname
• Example:
  visualvm --laf Metal
visualvm --laf com.my.LookAndFeel --cp:a %TEMP%\mylookandfeel.jar

• --fontsize Defines the base font size used in the VisualVM GUI.
• Usage:
  visualvm --fontsize <font_size>
• Example:
  visualvm --fontsize 15

Functional Options

• --openfile Opens the provided file or snapshot in the VisualVM GUI, if supported (.tdump, .hprof, .nps, .npss, .jfr, .apps).
• Usage:
  visualvm --openfile <file>
• Example:
  visualvm --openfile %TEMP%\recording.jfr

• --openid Opens a process with the provided id in the VisualVM GUI.
• The id is defined by the process' system property visualvm.id: java -Dvisualvm.id=custom_id -jar process.jar.
• Usage:
  visualvm --openid <id>
visualvm --openid <id@tab_idx> where tab_idx is a 1-based index of the process' tab to select
• Example:
  visualvm --openid custom_id
visualvm --openid custom_id@2

• --openpid Opens a process with the provided pid in the VisualVM GUI.
• Usage:
  visualvm --openpid <pid>
visualvm --openpid <pid@tab_idx> where tab_idx is a 1-based index of the process' tab to select
• Example:
  visualvm --openpid 12345
visualvm --openpid 12345@2

• --openjmx Opens a process specified by the provided JMX connection in the VisualVM GUI.
• Usage:
  visualvm --openjmx <host:port>
• Example:
  visualvm --openjmx 10.0.0.100:12345

• --threaddump Takes thread dump of the provided process and opens it in VisualVM GUI.
• Usage:
  visualvm --threaddump <pid>
• Example:
  visualvm --threaddump 12345

• --heapdump Takes heap dump of the provided process and opens it in VisualVM GUI.
• Usage:
  visualvm --heapdump <pid>
• Example:
  visualvm --heapdump 12345

• --start-cpu-sampler Starts CPU sampler session for the provided process.
• Usage:
  visualvm --start-cpu-sampler <pid> for default settings
  visualvm --start-cpu-sampler <pid@include-classes=<filter>,sampling-rate=<rate_ms>>
visualvm --start-cpu-sampler <pid@exclude-classes=<filter>,sampling-rate=<rate_ms>>
visualvm --start-cpu-sampler <pid@settings-file=<settings_file>>
• Example:
  visualvm --start-cpu-sampler 12345
visualvm --start-cpu-sampler 12345@exclude-classes=java.**,sampling-rate=20
visualvm --start-cpu-sampler 12345@settings-file=%TEMP%\sampler_settings.properties

• --start-memory-sampler Starts memory sampler session for the provided process.
• Usage:
  visualvm --start-memory-sampler <pid> for default settings
  visualvm --start-memory-sampler <pid@sampling-rate=<rate_ms>>
visualvm --start-memory-sampler <pid@settings-file=<settings_file>>
• Example:
  visualvm --start-memory-sampler 12345
visualvm --start-memory-sampler 12345@sampling-rate=2000
visualvm --start-memory-sampler 12345@settings-file=%TEMP%\sampler_settings.properties

• --snapshot-sampler Takes snapshot of the sampling data collected so far for the provided process.
• Usage:
  visualvm --snapshot-sampler <pid>
• Example:
  visualvm --snapshot-sampler 12345

• --stop-sampler Stops the sampler session of the provided process.
• Usage:
  visualvm --stop-sampler <pid>
• Example:
  visualvm --stop-sampler 12345

• --start-jfr Starts flight recording of the provided process.
• Usage:
  visualvm --start-jfr <pid> for default settings
  visualvm --start-jfr <pid@name=<recording_name>,settings=<jfr_settings>> for custom settings
  visualvm --start-jfr <pid@settings-file=<settings_file>> for custom settings defined in a properties file
• Example:
  visualvm --start-jfr 12345
visualvm --start-jfr 12345@name=MyRecording,settings=default
visualvm --start-jfr 12345@settings-file=%TEMP%\jfr_settings.properties

• --dump-jfr Dumps the flight recorder data collected so far for the provided process.
• Usage:
  visualvm --dump-jfr <pid>
• Example:
  visualvm --dump-jfr 12345

• --stop-jfr Stops the flight recording of the provided process.
• Usage:
  visualvm --stop-jfr <pid>
• Example:
  visualvm --stop-jfr 12345

• --source-roots Defines the source roots to be searched for the sources by VisualVM.
• Usage:
  visualvm --source-roots="<source_root[subpaths=subpath1:subpath2][encoding=encoding_name]>"
• Example:
  visualvm --source-roots="C:\Sources\Root1;C:\Sources\Root2[subpaths=src:test\src]" (Windows)
  visualvm --source-roots="/home/user/src/root1[encoding=UTF-16]:/home/user/src/root2" (macOS, Linux)
• Details:
  See the Sources Support document.

• --source-viewer Defines the command to launch an external sources viewer from VisualVM using Go to Source action.
• Usage:
  visualvm --source-viewer="<viewer_command>"
• Example:
  visualvm --source-viewer="C:\Software\VSCode\bin\code.cmd -g {file}:{line}:{column}"
• Details:
  See the Sources Support document.

• --source-config Defines --source-roots and --source-viewer in a single step using a properties file.
• The file contains at least one of source-roots and source-viewer key/value pair in java.util.Properties format, UTF-8 encoding.
• Usage:
  visualvm --source-config <config_file>
• Example:
  visualvm --source-config %TEMP%\source-config.properties
• Details:
  See the Sources Support document.

• --window-to-front Brings the currently opened VisualVM window to front if supported by the OS window system.
• Usage:
  visualvm --window-to-front

System Properties

Some VisualVM features or behavior can be configured using the system properties provided to the VisualVM launcher.
Make sure to use the visualvm -J-Dsystem.property=value format.

Selected VisualVM System Properties:

Note: System properties specific to VisualVM are not considered a stable API, they may vary among releases and/or be discontinued at any time.

• visualvm.tmpdir Defines location for storing temporary files like thread dumps, profiler snapshots, etc.
• Example:
  visualvm -J-Dvisualvm.tmpdir=%TEMP%\visualvm_tmpdir

• org.graalvm.visualvm.modules.startup.DisableStartupCheck Disables the initial check for a supported JDK on VisualVM startup.
• Example:
  visualvm -J-Dorg.graalvm.visualvm.modules.startup.DisableStartupCheck=true

• visualvm.search.process.timeout Maximum number milliseconds to wait for a process id/pid to become available when processing command line options like --openid, --threaddump, --start-cpu-sampler, etc.
• Example:
  visualvm -J-Dvisualvm.search.process.timeout=10000

• graphs.forceSpeed Special performance mode for the VisualVM charts disabling transparency & antialiasing.
• Example:
  visualvm -J-Dgraphs.forceSpeed=true

• OQLController.limitResults Maximum number of results returned by an OQL query in the heap viewer OQL Console.
• Example:
  visualvm -J-DOQLController.limitResults=200

Useful Apperance System Properties:

• sun.java2d.uiScale.enabled Enabling/disabling the implicit Swing scaling on high DPI displays.
• Example:
  visualvm -J-Dsun.java2d.uiScale.enabled=false

• sun.java2d.uiScale Definition of the UI scale for the implicit Swing scaling on high DPI displays.
• Example:
  visualvm -J-Dsun.java2d.uiScale=1.0

• jdk.gtk.version Definition of GTK engine version to render the VisualVM GUI.
• Example:
  visualvm -J-Djdk.gtk.version=2