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

# guestfs-ruby(3)

How to use libguestfs from Ruby

## NAME

guestfs-ruby - How to use libguestfs from Ruby

## SYNOPSIS

```
 require 'guestfs'
 g = Guestfs::Guestfs.new()
 g.add_drive_opts("disk.img",
                  :readonly => true, :format => "raw")
 g.launch()
```

## DESCRIPTION

This manual page documents how to call libguestfs from the Ruby 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).

### EXCEPTIONS

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

## EXAMPLE 1: CREATE A DISK IMAGE

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

 require 'guestfs'

 output = "disk.img"

 g = Guestfs::Guestfs.new()

 # Create a raw-format sparse disk image, 512 MB in size.
 g.disk_create (output, "raw", 512 * 1024 * 1024)

 # Set the trace flag so that we can see each libguestfs call.
 g.set_trace(1)

 # Attach the disk image to libguestfs.
 g.add_drive_opts(output, :format => "raw")

 # 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.
 devices = g.list_devices()
 if devices.length != 1 then
   raise "error: expected a single device from list-devices"
 end

 # 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.
 partitions = g.list_partitions()
 if partitions.length != 1 then
   raise "error: expected a single partition from list-partitions"
 end

 # 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")
 message = "Hello, world\n"
 g.write("/hello", message)
 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()
```

## EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

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

 require 'guestfs'

 if ARGV.length == 0
   puts "usage: inspect_vm disk.img"
   exit 1
 end
 disk = ARGV[0]

 g = Guestfs::Guestfs.new()

 # Attach the disk image read-only to libguestfs.
 g.add_drive_opts(disk, :readonly => true)

 # Run the libguestfs back-end.
 g.launch()

 # Ask libguestfs to inspect for operating systems.
 roots = g.inspect_os()
 if roots.length == 0
   puts "inspect_vm: no operating systems found"
   exit 1
 end

 for root in roots do
   printf("Root device: %s\n", root)

   # Print basic information about the operating system.
   printf("  Product name: %s\n", g.inspect_get_product_name(root))
   printf("  Version:      %d.%d\n",
          g.inspect_get_major_version(root),
          g.inspect_get_minor_version(root))
   printf("  Type:         %s\n", g.inspect_get_type(root))
   printf("  Distro:       %s\n", 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.
   mps = g.inspect_get_mountpoints(root)
   mps = mps.sort {|a,b| a[0].length <=> b[0].length}
   for mp in mps do
     begin
       g.mount_ro(mp[1], mp[0])
     rescue Guestfs::Error => msg
       printf("%s (ignored)\n", msg)
     end
   end

   # If /etc/issue.net file exists, print up to 3 lines.
   filename = "/etc/issue.net"
   if g.is_file filename then
     printf("--- %s ---\n", filename)
     lines = g.head_n(3, filename)
     for line in lines do
       puts line
     end
   end

   # Unmount everything.
   g.umount_all()
 end
```

## 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-java**(3)](/guestfs-java/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), http://libguestfs.org/.

## AUTHORS

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

## COPYRIGHT

Copyright (C) 2010-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.