guestfs-erlang(3)

📦 version 1.60.1, in arch rolling

🌸 NAME 🌸

okay bestie, this is the manual page for guestfs-erlang(3) from the Virtualization Support corner of the universe — guestfs-erlang — How to use libguestfs from Erlang. ✨

✨ SYNOPSIS ✨

the whole vibe in one block:

{ok, G} = guestfs:create(),
ok = guestfs:add_drive_opts(G, Disk,
                            [{format, "raw"}, {readonly, true}]),
ok = guestfs:launch(G),
[Device] = guestfs:list_devices(G),
ok = guestfs:close(G).

💖 DESCRIPTION 💖

okay so this page documents how to call libguestfs from the Erlang programming language. It 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) — no skipping, bestie. 💅

🎀 OPENING AND CLOSING THE HANDLE 🎀

The Erlang bindings are implemented using an external program called "erl-guestfs". This program must be on the current PATH, or else you should specify the full path to the program:

{ok, G} = guestfs:create().

{ok, G} = guestfs:create("/path/to/erl-guestfs").

G is the libguestfs handle which you should pass to other functions.

To close the handle:

ok = guestfs:close(G).

🦋 FUNCTIONS WITH OPTIONAL ARGUMENTS 🦋

For functions that take optional arguments, the first arguments are the non-optional ones. The last argument is a list of tuples supplying the remaining optional arguments.

ok = guestfs:add_drive_opts(G, Disk,
                            [{format, "raw"}, {readonly, true}]).

If the last argument would be an empty list, you can also omit it:

ok = guestfs:add_drive_opts(G, Disk).

🌈 RETURN VALUES AND ERRORS 🌈

On success, most functions return a Result term (which could be a list, string, tuple etc.). If there is nothing for the function to return, then the atom ok is returned.

On error, you would see one of the following tuples:

  • {error, Msg, Errno} — This indicates an ordinary error from the function. Msg is the error message (string) and Errno is the Unix error (integer). Errno can be zero. See "guestfs_last_errno" in guestfs(3).
  • {unknown, Function} — This indicates that the function you called is not known. Generally this means you are mixing "erl-guestfs" from another version of libguestfs, which you should not do. Function is the name of the unknown function.
  • {unknownarg, Arg} — This indicates that you called a function with optional arguments, with an unknown argument name. Arg is the name of the unknown argument.

🍓 EXAMPLE 1: CREATE A DISK IMAGE 🍓

here's the full script — create a disk image and slay:

#!/usr/bin/env escript
%%! -smp enable -sname create_disk debug verbose
% Example showing how to create a disk image.

main(_) ->
    Output = "disk.img",

    {ok, G} = guestfs:create(),

    % Create a raw-format sparse disk image, 512 MB in size.
    {ok, File} = file:open(Output, [raw, write, binary]),
    {ok, _} = file:position(File, 512 * 1024 * 1024 - 1),
    ok = file:write(File, " "),
    ok = file:close(File),

    % Set the trace flag so that we can see each libguestfs call.
    ok = guestfs:set_trace(G, true),

    % Attach the disk image to libguestfs.
    ok = guestfs:add_drive_opts(G, Output,
                                [{format, "raw"}, {readonly, false}]),

    % Run the libguestfs back-end.
    ok = guestfs:launch(G),

    % Get the list of devices.  Because we only added one drive
    % above, we expect that this list should contain a single
    % element.
    [Device] = guestfs:list_devices(G),

    % Partition the disk as one single MBR partition.
    ok = guestfs:part_disk(G, Device, "mbr"),

    % Get the list of partitions.  We expect a single element, which
    % is the partition we have just created.
    [Partition] = guestfs:list_partitions(G),

    % Create a filesystem on the partition.
    ok = guestfs:mkfs(G, "ext4", Partition),

    % Now mount the filesystem so that we can add files. *)
    ok = guestfs:mount(G, Partition, "/"),

    % Create some files and directories. *)
    ok = guestfs:touch(G, "/empty"),
    Message = "Hello, world\n",
    ok = guestfs:write(G, "/hello", Message),
    ok = guestfs:mkdir(G, "/foo"),

    % This one uploads the local file /etc/resolv.conf into
    % the disk image.
    ok = guestfs:upload(G, "/etc/resolv.conf", "/foo/resolv.conf"),

    % Because we wrote to the disk and we want to detect write
    % errors, call guestfs:shutdown.  You don't need to do this:
    % guestfs:close will do it implicitly.
    ok = guestfs:shutdown(G),

    % 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.
    ok = guestfs:close(G).

🧚 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE 🧚

and here's the inspect-a-VM-disk script, iconic behavior only:

#!/usr/bin/env escript
%%! -smp enable -sname inspect_vm debug verbose
% Example showing how to inspect a virtual machine disk.

main([Disk]) ->
    {ok, G} = guestfs:create(),

    % Attach the disk image read-only to libguestfs.
    ok = guestfs:add_drive_opts(G, Disk, [{readonly, true}]),

    % Run the libguestfs back-end.
    ok = guestfs:launch(G),

    % Ask libguestfs to inspect for operating systems.
    case guestfs:inspect_os(G) of
        [] ->
            io:fwrite("inspect_vm: no operating systems found~n"),
            exit(no_operating_system);
        Roots ->
            list_os(G, Roots)
    end.

list_os(_, []) ->
    ok;
list_os(G, [Root|Roots]) ->
    io:fwrite("Root device: ~s~n", [Root]),

    % Print basic information about the operating system.
    Product_name = guestfs:inspect_get_product_name(G, Root),
    io:fwrite("  Product name: ~s~n", [Product_name]),
    Major = guestfs:inspect_get_major_version(G, Root),
    Minor = guestfs:inspect_get_minor_version(G, Root),
    io:fwrite("  Version:      ~w.~w~n", [Major, Minor]),
    Type = guestfs:inspect_get_type(G, Root),
    io:fwrite("  Type:         ~s~n", [Type]),
    Distro = guestfs:inspect_get_distro(G, Root),
    io:fwrite("  Distro:       ~s~n", [Distro]),

    % Mount up the disks, like guestfish -i.
    Mps = sort_mps(guestfs:inspect_get_mountpoints(G, Root)),
    mount_mps(G, Mps),

    % If /etc/issue.net file exists, print up to 3 lines. *)
    Filename = "/etc/issue.net",
    Is_file = guestfs:is_file(G, Filename),
    if Is_file ->
            io:fwrite("--- ~s ---~n", [Filename]),
            Lines = guestfs:head_n(G, 3, Filename),
            write_lines(Lines);
       true -> ok
    end,

    % Unmount everything.
    ok = guestfs:umount_all(G),

    list_os(G, Roots).

% Sort keys by length, shortest first, so that we end up
% mounting the filesystems in the correct order.
sort_mps(Mps) ->
    Cmp = fun ({A,_}, {B,_}) ->
                  length(A) =< length(B) end,
    lists:sort(Cmp, Mps).

mount_mps(_, []) ->
    ok;
mount_mps(G, [{Mp, Dev}|Mps]) ->
    case guestfs:mount_ro(G, Dev, Mp) of
        ok -> ok;
        { error, Msg, _ } ->
            io:fwrite("~s (ignored)~n", [Msg])
    end,
    mount_mps(G, Mps).

write_lines([]) ->
    ok;
write_lines([Line|Lines]) ->
    io:fwrite("~s~n", [Line]),
    write_lines(Lines).

👑 SEE ALSO 👑

go read these icons: guestfs(3), guestfs-examples(3), guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3), guestfs-recipes(1), guestfs-ruby(3), http://www.erlang.org/. http://libguestfs.org/.

💜 AUTHORS 💜

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

Copyright (C) 2011-2025 Red Hat Inc.

💅 LICENSE 💅

the examples here are yours to use in your programs, fr fr. They may be freely copied, modified and distributed for any purpose without any restrictions. The page itself says: “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) and paste the complete, unedited output into the bug report.

and that's the whole page, bestie 💖 This one is from libguestfs-1.60.1, dated 2026-07-14 — go make something iconic. 🫶

📦 where this page comes from