---
name: "guestfs-java"
section: "3"
platform: "linux"
package: "java-libguestfs"
version: "1.60.1-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/guestfs-java"
---

# guestfs-java(3)

How to use libguestfs from Java

## NAME

guestfs-java - How to use libguestfs from Java

## SYNOPSIS

```
 import com.redhat.et.libguestfs.*;

 GuestFS g = new GuestFS ();
 g.add_drive ("disk.img",
              new HashMap<String,Object>() {
                {
                    put ("readonly", Boolean.TRUE);
                    put ("format", "raw");
                }
              });
 g.launch ();
```

## DESCRIPTION

This manual page documents how to call libguestfs from the Java programming language.  This page just documents the differences from the C API and gives some examples.  If you are not familiar with using libguestfs, you also need to read [**guestfs**(3)](/guestfs/3.md).

### CLOSING THE HANDLE

The handle is closed when it is reaped by the garbage collector. Because libguestfs handles include a lot of state, it is also possible to close (and hence free) them explicitly by calling the `"close"` method.

### EXCEPTIONS

Errors from libguestfs functions are mapped into the `"LibGuestFSException"` exception.  This has a single parameter which is the error message (a `"String"`).

Calling any method on a closed handle raises the same exception.

If [**malloc**(3)](/malloc/3.md) or some other allocation fails inside the bindings, the `"LibGuestFSOutOfMemory"` exception is thrown.

### EVENTS

The libguestfs event API is fully supported from Java.  Create a class which implements the `"EventCallback"` interface, create an instance of this class, and then call the `"GuestFS#set_event_callback"` method to register this instance.  The `"event"` method of the class is called when libguestfs generates an event.

For example, this will print all trace events:

```
 GuestFS g = new GuestFS ();
 g.set_trace (true);
 g.set_event_callback (
   new EventCallback () {
     public void event (long event, int eh,
                        String buffer, long[] array) {
       System.out.println (GuestFS.eventToString (event) +
                           ": " + buffer);
     }
   },
   GuestFS.EVENT_TRACE);
 g.add_drive_ro ("disk.img");
 // etc.
```

The output looks similar to this:

```
 EVENT_TRACE: add_drive_ro "disk.img"
 EVENT_TRACE: add_drive_ro = 0
 // etc.
```

### OPTIONAL ARGUMENTS

Some methods take an optional map of optional parameters.  An example of this is `"g.add_drive"` which can be called in one of two ways:

```
 g.add_drive ("disk.img");
```

or with optional arguments:

```
 Map<String, Object> optargs =
   new HashMap<String, Object>() {
   {
     put ("readonly", Boolean.TRUE);
     put ("format", "raw");
   }
 };
 g.add_drive ("disk.img", optargs);
```

For more information on this topic, see "CALLS WITH OPTIONAL ARGUMENTS" in [**guestfs**(3)](/guestfs/3.md).

*Optional handle parameters*

When creating the handle you can also pass a map of optional parameters:

```
 Map<String, Object> optargs =
   new HashMap<String, Object>() {
   {
     put ("close_on_exit", Boolean.FALSE);
     put ("environment", Boolean.TRUE);
   }
 };
 GuestFS g = new GuestFS (optargs);
```

For more information, see "guestfs\_create\_flags" in [**guestfs**(3)](/guestfs/3.md).

## COMPILING AND RUNNING

Libguestfs for Java is a Java Native Interface (JNI) extension, supplied in three parts:

- *libguestfs.jar*

  - *libguestfs-VERSION.jar*

  The pure Java JAR file which contains several classes, the primary one being `"com.redhat.et.libguestfs.GuestFS"`.  Upstream, the JAR file contains a version number in the filename, but some Linux distros may rename it without the version number.

- *libguestfs\_jni.so*

  The JNI code (written in C).  This contains private native functions that interface between Java code and the regular libguestfs C library. You should **not** call these directly.

- *libguestfs.so*

  The regular libguestfs C library.

To compile your Java program, you need to locate the JAR file and add it to the class path.  For example:

```
 export CLASSPATH=/usr/share/java/libguestfs.jar
 javac MyProgram.java
```

To run your Java program, you also need to ensure that the JAR file is on the class path, as well as the path of your program.  For example:

```
 export CLASSPATH=.:/usr/share/java/libguestfs.jar
 java MyProgram
```

## EXAMPLE 1: CREATE A DISK IMAGE

```
 // Example showing how to create a disk image.

 import java.io.*;
 import java.util.Map;
 import java.util.HashMap;
 import com.redhat.et.libguestfs.*;

 public class CreateDisk
 {
     static String output = "disk.img";

     public static void main (String[] argv)
     {
         try {
             GuestFS g = new GuestFS ();

             // Create a raw-format sparse disk image, 512 MB in size.
             RandomAccessFile f = new RandomAccessFile (output, "rw");
             f.setLength (512 * 1024 * 1024);
             f.close ();

             // Set the trace flag so that we can see each libguestfs call.
             g.set_trace (true);

             // Attach the disk image to libguestfs.
             @SuppressWarnings("serial") Map<String, Object> optargs =
                 new HashMap<String, Object>() {
                 {
                     put ("format", "raw");
                     put ("readonly", Boolean.FALSE);
                 }
             };
             g.add_drive_opts (output, optargs);

             // Run the libguestfs back-end.
             g.launch ();

             // Get the list of devices.  Because we only added one drive
             // above, we expect that this list should contain a single
             // element.
             String[] devices = g.list_devices ();
             if (devices.length != 1)
                 throw new Error ("expected a single device from list-devices");

             // Partition the disk as one single MBR partition.
             g.part_disk (devices[0], "mbr");

             // Get the list of partitions.  We expect a single element, which
             // is the partition we have just created.
             String[] partitions = g.list_partitions ();
             if (partitions.length != 1)
                 throw new Error ("expected a single partition from list-partitions");

             // Create a filesystem on the partition.
             g.mkfs ("ext4", partitions[0]);

             // Now mount the filesystem so that we can add files.
             g.mount (partitions[0], "/");

             // Create some files and directories.
             g.touch ("/empty");
             String message = "Hello, world\n";
             g.write ("/hello", message.getBytes());
             g.mkdir ("/foo");

             // This one uploads the local file /etc/resolv.conf into
             // the disk image.
             g.upload ("/etc/resolv.conf", "/foo/resolv.conf");

             // Because we wrote to the disk and we want to detect write
             // errors, call g.shutdown.  You don't need to do this:
             // g.close will do it implicitly.
             g.shutdown ();

             // Note also that handles are automatically closed if they are
             // reaped by the garbage collector.  You only need to call close
             // if you want to close the handle right away.
             g.close ();
         }
         catch (Exception exn) {
             System.err.println (exn);
             System.exit (1);
         }
     }
 }
```

## EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

```
 // Example showing how to inspect a virtual machine disk.

 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import com.redhat.et.libguestfs.*;

 public class InspectVM
 {
     static final Comparator<String> COMPARE_KEYS_LEN =
         new Comparator<String>() {
         public int compare (String k1, String k2) {
             return k1.length() - k2.length();
         }
     };

     public static void main (String[] argv)
     {
         try {
             if (argv.length != 1)
                 throw new Error ("usage: InspectVM disk.img");

             String disk = argv[0];

             GuestFS g = new GuestFS ();

             // Attach the disk image read-only to libguestfs.
             @SuppressWarnings("serial") Map<String, Object> optargs =
                 new HashMap<String, Object>() {
                 {
                     //put ("format", "raw");
                     put ("readonly", Boolean.TRUE);
                 }
             };

             g.add_drive_opts (disk, optargs);

             // Run the libguestfs back-end.
             g.launch ();

             // Ask libguestfs to inspect for operating systems.
             String roots[] = g.inspect_os ();
             if (roots.length == 0)
                 throw new Error ("inspect_vm: no operating systems found");

             for (String root : roots) {
                 System.out.println ("Root device: " + root);

                 // Print basic information about the operating system.
                 System.out.println ("  Product name: " +
                                     g.inspect_get_product_name (root));
                 System.out.println ("  Version:      " +
                                     g.inspect_get_major_version (root) +
                                     "." +
                                     g.inspect_get_minor_version (root));
                 System.out.println ("  Type:         " +
                                     g.inspect_get_type (root));
                 System.out.println ("  Distro:       " +
                                     g.inspect_get_distro (root));

                 // Mount up the disks, like guestfish -i.
                 //
                 // Sort keys by length, shortest first, so that we end up
                 // mounting the filesystems in the correct order.
                 Map<String,String> mps = g.inspect_get_mountpoints (root);
                 List<String> mps_keys = new ArrayList<String> (mps.keySet ());
                 Collections.sort (mps_keys, COMPARE_KEYS_LEN);

                 for (String mp : mps_keys) {
                     String dev = mps.get (mp);
                     try {
                         g.mount_ro (dev, mp);
                     }
                     catch (Exception exn) {
                         System.err.println (exn + " (ignored)");
                     }
                 }

                 // If /etc/issue.net file exists, print up to 3 lines.
                 String filename = "/etc/issue.net";
                 if (g.is_file (filename)) {
                     System.out.println ("--- " + filename + " ---");
                     String[] lines = g.head_n (3, filename);
                     for (String line : lines)
                         System.out.println (line);
                 }

                 // Unmount everything.
                 g.umount_all ();
             }
         }
         catch (Exception exn) {
             System.err.println (exn);
             System.exit (1);
         }
     }
 }
```

## SEE ALSO

[**guestfs**(3)](/guestfs/3.md), [**guestfs-examples**(3)](/guestfs-examples/3.md), [**guestfs-erlang**(3)](/guestfs-erlang/3.md), [**guestfs-golang**(3)](/guestfs-golang/3.md), [**guestfs-lua**(3)](/guestfs-lua/3.md), [**guestfs-ocaml**(3)](/guestfs-ocaml/3.md), [**guestfs-perl**(3)](/guestfs-perl/3.md), [**guestfs-python**(3)](/guestfs-python/3.md), [**guestfs-recipes**(1)](/guestfs-recipes/1.md), [**guestfs-ruby**(3)](/guestfs-ruby/3.md), http://libguestfs.org/, http://caml.inria.fr/.

## AUTHORS

Richard W.M. Jones (`"rjones at redhat dot com"`)

## COPYRIGHT

Copyright (C) 2011-2025 Red Hat Inc.

## LICENSE

This manual page contains examples which we hope you will use in your programs.  The examples may be freely copied, modified and distributed for any purpose without any restrictions.

## BUGS

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter\_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

- •

  The version of libguestfs.

- •

  Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

- •

  Describe the bug accurately and give a way to reproduce it.

- •

  Run [**libguestfs-test-tool**(1)](/libguestfs-test-tool/1.md) and paste the **complete, unedited** output into the bug report.