--- name: "guestfs-python" section: "3" platform: "linux" package: "python-libguestfs" version: "1.60.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/guestfs-python" --- # guestfs-python(3) How to use libguestfs from Python ## NAME guestfs-python - How to use libguestfs from Python ## SYNOPSIS ``` import guestfs g = guestfs.GuestFS(python_return_dict=True) g.add_drive_opts("disk.img", format="raw", readonly=1) g.launch() ``` ## DESCRIPTION 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)](/guestfs/3.md). ### python\_return\_dict=True All new code should construct the handle using: ``` g = guestfs.GuestFS(python_return_dict=True) ``` This indicates that your program wants to receive Python dicts for methods in the API that return hashtables. In a future version of libguestfs, this will become the default. ### EXCEPTIONS Errors from libguestfs functions are mapped into `"RuntimeError"` with a single string argument which is the error message. ### MORE DOCUMENTATION Type: ``` $ python >>> import guestfs >>> help(guestfs) ``` ### USING PYTHON BINDINGS IN A VIRTUALENV These bindings are *not* available in pypi owing to a licensing problem. See https://bugzilla.redhat.com/1075594 for current status. However we do publish a Python distribution for selected stable versions of libguestfs in http://libguestfs.org/download/python. You can use it like this: ``` 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() ``` ## 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-recipes**(1)](/guestfs-recipes/1.md), [**guestfs-ruby**(3)](/guestfs-ruby/3.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.