# VisualVM: building the all-in-one Java troubleshooting tool from source

> VisualVM bundles JDK command line tools with lightweight profiling in a NetBeans Platform application. The repository holds the source, not a download, and the README's build path expects Ant and JDK 8.

**oracle/visualvm** — VisualVM is an All-in-One Java Troubleshooting Tool

- Repository: https://github.com/oracle/visualvm
- Website: https://visualvm.github.io/
- Stars: 3,266 · Forks: 335
- Language: Java
- License: NOASSERTION
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/oracle-visualvm

## What VisualVM actually does for a running JVM

VisualVM is a visual tool that integrates command line JDK tools with lightweight profiling capabilities, according to the README. That sentence is the whole product thesis: instead of switching between jstack, jmap, jstat and a separate profiler, you get one window that attaches to a local or remote JVM and shows threads, heap, CPU and sampled call trees. The audience is Java engineers debugging a process that is already running: a service that leaks, a batch job that stalls, a desktop application that feels slow. It is not a build-time analyser and it does not instrument bytecode ahead of time. The repository itself is the master sources, and the README points readers to visualvm.github.io for details, downloads and documentation. If you only want the tool, that site is where the project says to get it. This repository matters when you need to build it yourself, patch it, or build the plugin suite against it.

## The NetBeans Platform dependency and the two project suites

The architecture is visible in the repository layout rather than in prose. There are two Ant suites: visualvm/visualvm for the core tool and visualvm/plugins for the plugins that ship through the Plugins Center. The core suite is a NetBeans Platform application, and the README requires NetBeans Platform 22 to be downloaded and extracted into visualvm/visualvm so that a netbeans directory appears there. That single decision explains most of the build friction: the platform is not vendored, it is a separate archive you fetch from the project's own release assets. The plugins suite is built on top of the core suite, and the README describes a chained flow: building or running the plugins suite first builds the core zip into visualvm/visualvm/dist/visualvm.zip, extracts it into visualvm/plugins/visualvm, and only then builds each plugin. Running the plugins suite starts VisualVM with all plugins installed. The samples directory is the other useful signal for plugin authors: samples/hellovvm/, samples/jvmcap/, samples/apptype/, samples/datasource/, samples/subnodes/ and samples/pluggableViewDemoSuite/ are separate starting points, each presumably demonstrating a different extension point. The README does not document what each sample does, so treat the directory names as the only map you get.

## Building VisualVM from source with Ant

The README is explicit about the toolchain: Apache Ant 1.9.15 or above and Oracle JDK 8. Both are build requirements, not runtime requirements, but the JDK 8 constraint is the one that catches people out, because a machine with only a newer JDK will not satisfy the documented build. The steps below follow the README in order.

Clone or download the repository into a directory named visualvm. The directory name matters because the rest of the instructions are written relative to it.

```bash
git clone https://github.com/oracle/visualvm.git visualvm
cd visualvm
```

Next, fetch the NetBeans Platform 22 archive linked from the README and extract it into visualvm/visualvm. The README states this should create visualvm/visualvm/netbeans.

```bash
cd visualvm
# download nb220_platform_20260621.zip from the 2.2.2 release assets
unzip nb220_platform_20260621.zip -d .
ls netbeans
```

With the platform in place, build the distribution zip from the core suite. The README gives ant build-zip as the command, run in the visualvm/visualvm directory.

```bash
cd visualvm/visualvm
ant build-zip
```

To start the tool without packaging it, the README gives ant run in the same directory.

```bash
ant run
```

If you want the plugin suite as well, the README says to use ant build or ant run in the visualvm/plugins directory. That path rebuilds the core zip and extracts it before building the individual plugins, so expect a longer first run.

```bash
cd ../plugins
ant build
```

## Where VisualVM stops being the right tool

The most concrete limitation is the build requirement itself. Oracle JDK 8 and Ant 1.9.15 or above are stated in the README, and nothing in the repository suggests a newer JDK is supported for building. A team that has standardised on a current JDK for its build agents has to add a second JDK just to compile this, or use the published binary instead. The second limitation is sampling. The README describes the profiling as lightweight, which is a real constraint: lightweight sampling gives you a statistical view of where time goes, not an exact per-invocation accounting, so a method that is called rarely but blocks for a long time can be under-represented. If you need allocation-level attribution or deterministic call counts, sampling is the wrong instrument. Third, contributions are restricted. The README states that for legal reasons the project cannot accept external pull requests, and directs readers to CONTRIBUTING.md. That is unusual and worth knowing before you plan a patch: you can file an RFE or bug, and you can leave feedback through the site's feedback page, but you cannot upstream code. Finally, the README does not document rollback, version pinning or an upgrade path for the built artifact, so if you distribute a build internally you are on your own for tracking which platform archive pairs with which source revision.

## How VisualVM differs from IDE-embedded profilers

The obvious alternative is the profiler built into an IDE. IntelliJ IDEA ships its own profiler, and the related search data shows people actively looking for how to use VisualVM inside IntelliJ, which suggests the two are often compared rather than combined. The difference in approach is where the process lives. An IDE profiler assumes your application is launched from that IDE or attached through its run configuration, and the analysis surface is the editor window you already have open. VisualVM is a separate desktop application that attaches to a JVM, local or remote, and it does not care how that JVM was started. That makes it the better fit for a process you cannot relaunch from an IDE: a staging server, a customer's machine, a long-running service. It makes it the worse fit when you are iterating on code in the editor and want the profile inline. The trade is convenience against reach. A second alternative is a dedicated commercial profiler, which typically offers deeper instrumentation and allocation tracking than a lightweight sampler; the cost is a licence and, usually, an agent that has to be attached to the target JVM.

## Licence and upgrade cost of running your own build

The README states the project is released under the GNU General Public License, version 2, with the Classpath Exception, with copyright held by Oracle and/or its affiliates. The Classpath Exception is the part that matters for most teams: it exists so that linking the code with independent modules does not force those modules under the GPL. That said, the repository metadata labels the licence as NOASSERTION, and the README points at LICENSE.txt and THIRDPARTYLICENSE rather than spelling out the terms in full. If you redistribute a build, read those two files and get your own legal review; nothing here is legal advice. On upgrade cost, the release cadence visible in the release history is slow and uneven: 2.2 in April 2025, 2.2.1 in February 2026, and 2.2.2 in September 2026, with the last push to master on 2026-09-18. A source build pins you to a platform archive that changes between releases, so an upgrade means re-downloading the matching NetBeans Platform version and rebuilding, not just pulling the latest commit. If you do not need to modify VisualVM, taking the binary from visualvm.github.io removes that recurring cost entirely.

## Conclusion

Adopt VisualVM if you need a desktop tool that combines JDK command line utilities with lightweight profiling and you are willing to build it or take the binary from visualvm.github.io. Skip it if you need an IDE-integrated profiler inside IntelliJ or a build that runs on a modern JDK without a separate platform download. Before committing, verify that your JDK 8 install is present, that the NetBeans Platform 22 archive extracts to visualvm/visualvm/netbeans, and that the GPLv2 with Classpath Exception terms fit how you redistribute the result.

## FAQ

### What is VisualVM used for?

It is a visual tool that integrates command line JDK tools with lightweight profiling capabilities, per the README. In practice that means attaching to a running JVM to inspect threads, memory and CPU behaviour from one window.

### Is Java VisualVM free?

The README states the project is released under the GNU General Public License, version 2, with the Classpath Exception, with copyright held by Oracle and/or its affiliates. Downloads and documentation are pointed to visualvm.github.io.

### How do I install VisualVM?

The README does not give an installer. It says the project's downloads are at visualvm.github.io, and it documents building from source with Apache Ant 1.9.15 or above and Oracle JDK 8.

### How do I run VisualVM from the source repository?

After extracting NetBeans Platform 22 into visualvm/visualvm, the README gives ant run in the visualvm/visualvm directory to start the tool, or ant build-zip to produce the distribution zip.

### How do I use the VisualVM profiler?

The README describes the profiling only as lightweight, and the tool is documented at visualvm.github.io rather than in the repository. The repository itself covers building and running, not profiling workflows.

### Can I use VisualVM inside IntelliJ IDEA?

Neither the README nor the repository files describe any IntelliJ integration. VisualVM is built as a standalone NetBeans Platform application that you start with ant run or from the published download.

## Sources

- [Issues](https://github.com/oracle/visualvm/issues)
- [oracle/visualvm on GitHub](https://github.com/oracle/visualvm)
- [Project website](https://visualvm.github.io/)
- [README](https://github.com/oracle/visualvm/blob/master/README.md)
- [Releases](https://github.com/oracle/visualvm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oracle-visualvm