iTranslated by AI
A Guide for Everyone Who Wants to Build Their Own Java Virtual Machine
Introduction
Celebrate! Java 25 Released
As you all Java lovers likely know, Java 25 was released recently (September 16, 2025).
In particular, this version is a Long-Term Support (LTS) release, the first in two years following Java 21, and is expected to be widely adopted as a version that can be used with peace of mind in enterprise environments.
For comparisons with previous versions and notable points, please refer to the excellent article on Qiita.
Java Language Specification and JVM Mechanisms are Public
By the way, all Java language specifications and the mechanisms of the Java Virtual Machine (JVM) are debated through proposals such as JEP (JDK Enhancement Proposal) and JSR (Java Specification Request), and are ultimately incorporated into the OpenJDK project.
These proposals and discussions are widely published on the OpenJDK JDK Wiki and the JEP Index, and anyone can view them.
Furthermore, the Java language specification and the JVM specification are defined in detail in Oracle's The Java® Language Specification and The Java® Virtual Machine Specification, which are also available for anyone to view. In other words, the Java language specification and the mechanisms of the JVM evolve through an open process, and anyone can learn and understand their details.
One of the most effective indicators of this level of understanding is whether or not you can build your own JVM. If you deeply understand the Java language specification and how the JVM works, you would likely be able to create one yourself. However, when you actually try to build a JVM, you will likely be overwhelmed by the sheer volume of information and its complexity.
Creating a DIY JVM is Still a High Hurdle
If you try to deeply understand the Java language specification and JVM mechanisms from these specification documents, you will likely be overwhelmed by the vast amount of information and the complexity involved. In particular, the JVM specification is extremely lengthy and contains many obscure details, making it a high hurdle for beginners.
Moreover, resources for learning Java language specifications and JVM mechanisms are very limited, and they are not always easy for beginners to understand. For instance, tutorials and notes on building your own C compiler or LLVM can be found in abundance with a quick search, but it seems that not many people set out to build their own JVM.
For this reason, I have been providing a guide for deciphering JVM specifications in a series called Reading the JVM (which is still ongoing). However, when I actually tried to implement a JVM myself, I realized that reading the specifications alone is not enough; it is essential to actually get your hands dirty and engage in trial and error.
I personally faced many challenges in the process of building my own JVM.
In this article, I would like to share knowledge and resources that are useful for those who, like me, want to build or are currently building their own JVM.
Reasons to Build Your Own JVM
Readers of this article may not necessarily have the burning desire to build a JVM. However, building one is an incredibly enjoyable endeavor, and it is undeniably a 'three-or-four-birds-with-one-stone' experience, as you will gain a wealth of knowledge along the way.
Note that this article is not a tutorial on how to build a JVM; rather, its purpose is to introduce the significance of building one and the necessary knowledge and resources to do so. Therefore, I will not delve too deeply into concrete implementation methods or code examples (though I will touch upon them as much as possible).
JVM Runs on 3 Billion Devices
Since around 2010, Oracle has been using the slogan 'Java runs on 3 billion devices.' While they say Java, this refers, of course, to the JVM.
These 3 billion devices naturally include your computers and Android devices, but they also include household appliances, embedded systems, and IoT devices.
For example, if you happen to possess a My Number Card, certain Resident Basic Ledger cards, or an Estonian national ID card, you are using a Java platform that runs on Java Card, a smart card implementation that is a subset of the JVM. These cards are devices where security is paramount, and Java Card is a type of JVM specifically designed for that purpose.
Furthermore, the now-defunct Java Ring, a ring-shaped wearable device, was also equipped with a JVM.
JVM Runs on Every Device
Theoretically, every Turing-complete device on Earth can implement a JVM. If, in the future, you want to run Minecraft instead of DOOM on some hacky mystery device, having the skills to build a JVM will be a giant leap toward making that a reality.
In recent DOOM porting trends, it is common to first implement the RISC-V architecture on the target device, port Linux to run on that RISC-V environment, and then finally run DOOM. Therefore, the skills to build a JVM will surely be useful for porting Minecraft as well.
JVMs are Educational
On a more serious note, building a JVM is a fantastic way to learn many important concepts in computer science. For example, memory management, garbage collection, threads and synchronization, and bytecode interpretation and optimization are all fascinating topics involved in JVM implementation. It goes without saying that these topics are crucial in modern software development, and building a JVM allows you to understand them deeply.
As the name 'Virtual Machine' implies, the JVM is a kind of small computer. If you think of building a JVM as being similar to building a CPU emulator, you might get a sense of why it is fun. There are many unique instructions and concepts; for instance, frames, class loaders, and monitor features are JVM-specific concepts that do not exist in standard CPUs. If you have already emulated a CPU and are looking for something new, building a JVM is the perfect next step.
Furthermore, as mentioned earlier, the JVM includes features for thread scheduling and heap management. If you ever aspire to build your own OS, building a JVM is excellent preparation.
A JVM is More Than Just a CPU Emulator
Unlike a simple CPU emulator, the JVM is packed with unique innovations.
For example, the operands of an x86 call instruction directly specify the address of the function to be called. Moreover, this simply jumps to an address, with no significant support for arguments or return values.
On the other hand, JVM function-call instructions come in five types: invokevirtual, invokespecial, invokestatic, invokeinterface, and invokedynamic, each calling functions in different ways. Furthermore, these have built-in support for managing arguments and return values, resolving overloading, and dynamic binding.
The operands include the name and signature (type information for arguments and return values) of the function to be called, which the JVM uses to find the appropriate function.
In this way, the JVM provides high-level features such as function invocation and memory management, unlike a mere CPU emulator. Therefore, building a JVM will offer you much more learning and challenge than building a simple CPU emulator.
The Ultimate Choice You Face First
When building a JVM, the first thing you must choose is at what level you will implement the JVM.
If you start building one without knowing this, you will likely hit a wall in the middle for reasons described later (as I did). Therefore, clearly defining your goal at the start is the key to success in building your own JVM.
There are roughly four levels of JVM implementation, each with its own pros, cons, and vastly different levels of difficulty:
- A very simple JVM that interprets and executes instructions: Green
- A minimal JVM with basic features: Yellow
- A full-featured JVM supporting every Java program: Purple
- A high-performance JVM with advanced features like a JIT compiler: Red

Note that these classifications are my own definitions and are not official or rigid. Furthermore, these levels are not mutually exclusive; for instance, you can add a JIT compiler to a minimal JVM. I highly recommend implementing them sequentially, step by step.
1. A Very Simple JVM That Interprets and Executes Instructions
The most basic level of a JVM is a simple implementation that just interprets and executes JVM bytecode. This level focuses on implementing an interpreter to understand and execute the JVM instruction set sequentially.
The goal of this level of JVM is to support basic instructions such as arithmetic operations and variable access in Java, allowing it to execute simple JVM bytecode.
The JVM does not execute Java source code directly. Java source code is first converted into JVM bytecode by a compiler, and the JVM interprets and executes this bytecode. In other words, the JVM does not execute the source code itself, but rather its incarnation: bytecode.
Bytecode is a set of low-level instructions designed according to the JVM instruction set, efficiently representing Java source code. For example, to add int variables in Java, you write i + j in source code, but the JVM uses an instruction called iadd.
In the current JVM (Java 25), 205 instructions are defined, but at this implementation level, supporting only the bare minimum is sufficient.
Furthermore, the JVM is a stack-based virtual machine that uses a data structure called the operand stack for executing instructions. For example, the iadd instruction pops the top two int values from the operand stack, adds them together, and pushes the result back onto the stack.
By implementing a simple JVM, you can learn basic concepts such as stack implementation/manipulation and instruction decoding/execution. While this level is a good starting point to understand the basics of Java, it still lacks many features necessary to run actual Java programs.
Once you clear this stage, you will be able to execute Java programs like the following:
1 + 2;
3 * 10;
(1 + 2) ^ 3 >> 2;
For more details, please refer to my short article, "To Everyone Who Wants to Build a Simple Java Virtual Machine."
2. A Minimal JVM with Basic Features
A minimal JVM with basic features supports the entire JVM instruction set and implements essential functions such as method invocation, exception handling, and a small number of VM native methods. This level serves as a solid foundation for understanding Java's core features and executing simple Java programs.
The goal at this level is to implement the entire JVM instruction set and support basic features like method invocation and exception handling.
Implementing the entire instruction set is not particularly difficult in the grand scheme of building a JVM. Each instruction is reasonably abstracted and not overly complex. With only 205 instructions, it is not an overwhelming number. Compared to CPU architectures like x86 or ARM, the JVM instruction set is extremely simple and easy to implement.
However, simply implementing the entire instruction set does not result in a practical (or long-lasting) JVM. The next challenge you must consider is method invocation.
The JVM manages method calls using a data structure called a "Frame." Within a frame, local variables, the operand stack, and method arguments/return values are stored. Every time a method is called, the JVM creates a new frame and pushes it onto a stack structure known as the "Java Virtual Machine Stack." Each time a method is invoked, a new frame is pushed, and when execution finishes (whether it succeeds or fails), the frame is popped from the stack.
Furthermore, if you want to display messages to the console using standard output, you must implement the System.out.println method. This method calls native methods related to file operations, such as those found in standard library classes like FileDescriptor. Consequently, the number of methods you need to implement will grow like a chain reaction. Trying to implement all of them at this stage, however, would require an immense amount of effort and might lead you to give up. Therefore, I recommend implementing only the bare minimum number of VM native methods here. For instance, when the System.out.println method is called, you can mock it by having it write strings directly to the host OS's standard output instead of executing it as a regular Java method. This allows you to achieve console output easily without implementing the vast majority of the standard library.
By implementing a JVM at this level, you will gain a deeper understanding of Java's fundamentals and be able to execute simple Java programs.
Once you clear this stage, you will be able to execute Java programs like the following:
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
For more details, please refer to my short article, "To Everyone Who Wants to Build a Minimal Java Virtual Machine."
3. A Full-Featured JVM with Complete Standard Library Support
A full-featured JVM implements all functions defined in the JVM specification to support every possible Java program. This includes garbage collection, thread management, and full support for the standard library.
The goal at this level is to achieve complete standard library support and ensure that the System.initPhase1() through System.initPhase3() methods execute without errors.
Modern Java programs rely heavily on the OpenJDK standard library. For example, the collections framework in the java.util package, input/output functions in the java.io package, and networking features in the java.net package are widely used. Providing full support for these standard libraries is essential for creating a practical JVM.
While complete standard library support might sound daunting, it essentially boils down to implementing all the native methods required by the VM. Examples include wait and notify in java.lang.Object, get and set in the Field class, and thread management methods in the Thread class. By implementing these native methods, you enable many functionalities of the standard library.
Crucially, do not overlook the invocation of System.initPhase1() through System.initPhase3(). These methods perform the initialization required to launch the standard library, such as initializing the out field of the System class and the java.lang.ClassLoader class. They also launch threads like the object finalizer thread.
By ensuring these methods run without error, you will reach the goal for this level. Once you clear this stage, you will be able to execute almost any Java program (that does not require specific, unsupported native methods).
4. A High-Performance JVM with Advanced Features like JIT Compilers
A high-performance JVM includes advanced features such as a Just-In-Time (JIT) compiler, garbage collection, and thread management. It also includes support for JNI (Java Native Interface) via native methods.
Implementing these advanced features not only significantly improves the performance of Java programs but also allows your JVM to match the functionality provided by the OpenJDK implementation.
The goal at this level is to further enhance your level 3 JVM by implementing advanced features like a JIT compiler and garbage collection.
A JIT compiler improves program execution speed by converting JVM bytecode into native code, allowing Java programs to achieve performance comparable to native applications. Garbage collection automates memory management, preventing issues like memory leaks and dangling pointers, which ensures stable operation and efficient memory usage.
For instance, the aforementioned System.initPhase1() method might take about 5 to 20 seconds to execute if implemented naively. By implementing advanced features like a JIT compiler or CDS (Class Data Sharing), you can reduce this initialization time to a few hundred milliseconds, drastically improving Java program startup time.
Furthermore, JNI support is essential for interoperability with native code written in C/C++. By implementing the System.loadLibrary method, you enable Java programs to dynamically load native libraries and call functions within them. This requires understanding and properly implementing JNI specifications, while potentially referencing proposals like JEP 454 (Foreign Function & Memory API).
Implementing a JVM at this level allows you to realize a high-performance JVM with capabilities equivalent to the OpenJDK.
Useful Knowledge and Resources for Building a JVM
To build your own JVM, the following knowledge and resources will be helpful. These are selected based on what I personally found useful during my own JVM development process. They serve as an excellent starting point for systematically learning the knowledge required to build a JVM.
1. Official Specifications and Documentation
- The Java® Virtual Machine Specification: The official JVM specification. This is one of the most important resources for building a JVM. Because it is updated with every version, understanding the transitions and differences between versions will enable you to implement more versatile features.
- The Java® Language Specification: The official specification for the Java language. While it may seem limited to the language itself, it contains descriptions regarding the standard library and JVM behavior, which are frequently helpful when building a JVM.
The official documents above are the most critical resources for learning the knowledge needed to build a JVM. Both are available in HTML and PDF formats for free. The HTML version is convenient for reading on a screen, while the PDF version is suitable for printing and reading as a handbook. I personally prefer the latter and use a printed copy as a handbook.

Note that the JVM specification is extremely long and written in English. For someone with limited English proficiency (like myself), reading it is a struggle. Therefore, I provide a guide to reading the JVM specification through my article series, "Reading the JVM." I hope this series serves as a good starting point for navigating the specification step-by-step.
2. Open Source JVM Implementations
-
OpenJDK: The open-source Java Development Kit led by Oracle. OpenJDK includes the de facto standard HotSpot implementation, and its source code is publicly available on GitHub: openjdk/jdk. For those aiming for implementation level 3 or higher, referencing the standard library and its implementation source code is highly beneficial. Reading the actual source code is the fastest way to understand the detailed behavior of native methods the VM must implement (such as
Object.waitorClass.forName). - Eclipse OpenJ9: An open-source JVM implementation led by IBM. Its source code is also available on GitHub: eclipse/openj9. OpenJ9 is based on a design philosophy different from HotSpot, with a focus on embedded systems and cloud environments. Reading OpenJ9's source code allows you to learn about alternative implementation approaches and optimization techniques.
3. Community Projects and Commentary Articles
- Java VM Building Method: A simple JVM implementation in the R language by igjit. In terms of this article's classification, this corresponds to Level 2 (Minimal JVM).
-
gojvm: An implementation of a JVM in the Go language by DQNEO. This also corresponds to Level 2. A key feature is that all the code is contained within a single
main.gofile, making it very readable. - Building a JVM in PHP and outputting HelloWorld: A JVM implementation in PHP by memory. This person is well-known in the JVM building community. You may have seen this before arriving at this article. It is packed with insights on how to read the specification and implement a JVM. Even if you don't intend to build a JVM in PHP, this slide deck is worth a read.
Useful Tools
Byte-Me is a web application for visually analyzing and understanding JVM bytecode. It is a fantastic tool for learning the instruction set and structure of JVM bytecode!
For example, if you input Java source code, it generates the corresponding JVM bytecode and displays detailed descriptions for each instruction, helping you intuitively understand how each instruction works.

Additionally, there is FullJEP, a sister site to Byte-Me. It is a web application that allows for full-text search and browsing of JEPs (JDK Enhancement Proposals). JEPs are documents summarizing new features and improvement proposals for the Java platform and are very useful when building a JVM.

4. The Java Compatibility Kit (JCK)
The Java Compatibility Kit (JCK) is a test suite used to verify the compatibility of Java platform implementations. It is used to confirm that a JVM conforms to the Java SE specification. JCK is provided for each version of Java and is very useful in JVM development—for instance, by running TCK test cases to verify that your JVM features are working correctly. This improves the quality of your implementation.
However, using JCK requires an application and approval from the OpenJDK community, and license fees may apply for commercial use. It is quite difficult to access for individual study purposes.
Conclusion
Building your own JVM is an excellent way to deeply understand the Java language specification and the internal workings of the JVM. This article introduced the reasons for building a JVM and the necessary knowledge and resources. If you are interested in building a JVM, please use this article as a reference.
I hope you gain a lot of knowledge and enjoyment during the process of building your JVM. I hope this article is helpful to those who are interested in or currently building their own JVM. If you have any questions or feedback regarding this article, please let me know in the comments section.
Happy bytecode hacking!
References & Links
- Lindholm, T., Yellin, F., Bracha, G., & Smith, W. M. D. (2025). The Java® Virtual Machine Specification: Java SE 25 Edition.
- Otavio, S. (2024). Mastering the Java Virtual Machine. Packet Publishing. ISBN 978-1-835-46796-1
Discussion