--- name: "guestfs-golang" section: "3" platform: "linux" package: "libguestfs" version: "1.60.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/guestfs-golang" --- # guestfs-golang(3) How to use libguestfs from Go ## NAME guestfs-golang - How to use libguestfs from Go ## SYNOPSIS ``` import "libguestfs.org/guestfs" g, errno := guestfs.Create () if errno != nil { panic (fmt.Sprintf ("could not create handle: %s", errno)) } defer g.Close () if err := g.Add_drive ("test.img"); err != nil { panic (err) } if err := g.Launch (); err != nil { panic (err) } if err := g.Shutdown (); err != nil { panic (err) } ``` ## DESCRIPTION This manual page documents how to call libguestfs from the Go 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). ### IMPORTING THE MODULE The module is called `"guestfs"`. The full package name to import is `"libguestfs.org/guestfs"`. ### CREATING AND CLOSING THE HANDLE Use either `"guestfs.Create"` or `"guestfs.Create_flags"` to create the handle. The handle is closed implicitly if it is garbage collected. However it is probably a good idea to close it explicitly, either by calling `"g.Close ()"` or by deferring the same. ### ERRORS `"guestfs.Create"` and `"guestfs.Create_flags"` return a simple `*error`, which is really just a C `"errno"` wrapped up in the appropriate golang struct. All other calls return a `*GuestfsError` which (if non-nil) is a richer struct that contains the error string from libguestfs, the errno (if available) and the operation which failed. This can also be converted to a string for display. ### LIMITATIONS - • No support for events (see "EVENTS" in [**guestfs**(3)](/guestfs/3.md)). - • UUIDs are not returned in structures. ## EXAMPLE 1: CREATE A DISK IMAGE ``` /* Example showing how to create a disk image. */ package main import ( "fmt" "libguestfs.org/guestfs" ) func main() { output := "disk.img" g, errno := guestfs.Create () if errno != nil { panic (errno) } defer g.Close () /* Create a raw-format sparse disk image, 512 MB in size. */ if err := g.Disk_create (output, "raw", 512 * 1024 * 1024); err != nil { panic (err) } /* Set the trace flag so that we can see each libguestfs call. */ g.Set_trace (true) /* Attach the disk image to libguestfs. */ optargs := guestfs.OptargsAdd_drive{ Format_is_set: true, Format: "raw", Readonly_is_set: true, Readonly: false, } if err := g.Add_drive (output, &optargs); err != nil { panic (err) } /* Run the libguestfs back-end. */ if err := g.Launch (); err != nil { panic (err) } /* Get the list of devices. Because we only added one drive * above, we expect that this list should contain a single * element. */ devices, err := g.List_devices () if err != nil { panic (err) } if len(devices) != 1 { panic ("expected a single device from list-devices") } /* Partition the disk as one single MBR partition. */ err = g.Part_disk (devices[0], "mbr") if err != nil { panic (err) } /* Get the list of partitions. We expect a single element, which * is the partition we have just created. */ partitions, err := g.List_partitions () if err != nil { panic (err) } if len(partitions) != 1 { panic ("expected a single partition from list-partitions") } /* Create a filesystem on the partition. */ err = g.Mkfs ("ext4", partitions[0], nil) if err != nil { panic (err) } /* Now mount the filesystem so that we can add files. */ err = g.Mount (partitions[0], "/") if err != nil { panic (err) } /* Create some files and directories. */ err = g.Touch ("/empty") if err != nil { panic (err) } message := []byte("Hello, world\n") err = g.Write ("/hello", message) if err != nil { panic (err) } err = g.Mkdir ("/foo") if err != nil { panic (err) } /* This one uploads the local file /etc/resolv.conf into * the disk image. */ err = g.Upload ("/etc/resolv.conf", "/foo/resolv.conf") if err != nil { panic (err) } /* 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. */ if err = g.Shutdown (); err != nil { panic (fmt.Sprintf ("write to disk failed: %s", err)) } } ``` ## EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE ``` /* Example showing how to inspect a virtual machine disk. */ package main import ( "fmt" "os" "libguestfs.org/guestfs" ) func main() { if len(os.Args) < 2 { panic ("usage: inspect-vm disk.img") } disk := os.Args[1] g, errno := guestfs.Create () if errno != nil { panic (fmt.Sprintf ("could not create handle: %s", errno)) } /* Attach the disk image read-only to libguestfs. */ optargs := guestfs.OptargsAdd_drive{ Format_is_set: true, Format: "raw", Readonly_is_set: true, Readonly: true, } if err := g.Add_drive (disk, &optargs); err != nil { panic (err) } /* Run the libguestfs back-end. */ if err := g.Launch (); err != nil { panic (err) } /* Ask libguestfs to inspect for operating systems. */ roots, err := g.Inspect_os () if err != nil { panic (err) } if len(roots) == 0 { panic ("inspect-vm: no operating systems found") } for _, root := range roots { fmt.Printf ("Root device: %s\n", root) /* Print basic information about the operating system. */ s, _ := g.Inspect_get_product_name (root) fmt.Printf (" Product name: %s\n", s) major, _ := g.Inspect_get_major_version (root) minor, _ := g.Inspect_get_minor_version (root) fmt.Printf (" Version: %d.%d\n", major, minor) s, _ = g.Inspect_get_type (root) fmt.Printf (" Type: %s\n", s) s, _ = g.Inspect_get_distro (root) fmt.Printf (" Distro: %s\n", s) /* XXX Incomplete example. Sorting the keys by length * is unnecessarily hard in golang. */ } } ``` ## SEE ALSO [**guestfs**(3)](/guestfs/3.md), [**guestfs-examples**(3)](/guestfs-examples/3.md), [**guestfs-erlang**(3)](/guestfs-erlang/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), [**guestfs-ruby**(3)](/guestfs-ruby/3.md), http://www.golang.org/, http://libguestfs.org/. ## AUTHORS Richard W.M. Jones (`"rjones at redhat dot com"`) ## COPYRIGHT Copyright (C) 2013 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.