guestfs-python3

Usage

 import guestfs
 g = guestfs.GuestFS(python_return_dict=True)
 g.add_drive_opts("disk.img", format="raw", readonly=1)
 g.launch()

Overview

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

 g = guestfs.GuestFS(python_return_dict=True)

 $ python
 >>> import guestfs
 >>> help(guestfs)

 pip install http://libguestfs.org/download/python/guestfs-1.XX.YY.tar.gz

Example 1: create a disk image

 # Example showing how to create a disk image.
 
 import guestfs
 
 output = "disk.img"
 
 # All new Python code should pass python_return_dict=True
 # to the constructor.  It indicates that your program wants
 # to receive Python dicts for methods in the API that return
 # hashtables.
 g = guestfs.GuestFS(python_return_dict=True)
 
 # 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", readonly=0)
 
 # 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()
 assert (len(devices) == 1)
 
 # 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()
 assert (len(partitions) == 1)
 
 # 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 reference counting.  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.
 
 import sys
 import guestfs
 
 if len(sys.argv) < 2:
     print("inspect_vm: missing disk image to inspect", file=sys.stderr)
     sys.exit(1)
 disk = sys.argv[1]
 
 # All new Python code should pass python_return_dict=True
 # to the constructor.  It indicates that your program wants
 # to receive Python dicts for methods in the API that return
 # hashtables.
 g = guestfs.GuestFS(python_return_dict=True)
 
 # Attach the disk image read-only to libguestfs.
 g.add_drive_opts(disk, readonly=1)
 
 # Run the libguestfs back-end.
 g.launch()
 
 # Ask libguestfs to inspect for operating systems.
 roots = g.inspect_os()
 if len(roots) == 0:
     print("inspect_vm: no operating systems found", file=sys.stderr)
     sys.exit(1)
 
 for root in roots:
     print("Root device: %s" % root)
 
     # Print basic information about the operating system.
     print("  Product name: %s" % (g.inspect_get_product_name(root)))
     print("  Version:      %d.%d" %
           (g.inspect_get_major_version(root),
            g.inspect_get_minor_version(root)))
     print("  Type:         %s" % (g.inspect_get_type(root)))
     print("  Distro:       %s" % (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)
     for device, mp in sorted(mps.items(), key=lambda k: len(k[0])):
         try:
             g.mount_ro(mp, device)
         except RuntimeError as msg:
             print("%s (ignored)" % msg)
 
     # If /etc/issue.net file exists, print up to 3 lines.
     filename = "/etc/issue.net"
     if g.is_file(filename):
         print("--- %s ---" % filename)
         lines = g.head_n(3, filename)
         for line in lines:
             print(line)
 
     # Unmount everything.
     g.umount_all()