guestmount(1)

📦
version 1.61.3 · 14 versions
, in centos-stream 10

🦋 guestmount(1) — the libguestfs girlies' fave 🦋

okay so first things first, this is a page from the Virtualization Support manual section, and it's literally called guestmount(1). Buckle up bestie, we're mounting filesystems 💅

✨ NAME ✨

guestmount — mount a guest filesystem on the host using FUSE and libguestfs 🫶

🌸 SYNOPSIS 🌸

the three iconic forms, no cap:

guestmount [--options] -a disk.img -m device [--ro] mountpoint

guestmount [--options] -a disk.img -i [--ro] mountpoint

guestmount [--options] -d Guest -i [--ro] mountpoint

🚨 WARNING 🚨

bestie. listen to me. Using guestmount in write mode on live virtual machines, or concurrently with other disk editing tools, can be dangerous — potentially causing disk corruption. 😭 The virtual machine must be shut down before you use this command, and disk images must not be edited concurrently.

Use the --ro (read-only) option to use guestmount safely if the disk image or virtual machine might be live. You may see strange or inconsistent results if running concurrently with other changes, but with this option you won't risk disk corruption. 🙏

fr fr, --ro is your bestie. write mode on a live VM is giving "chaos main character" and not in a cute way 💀

💖 DESCRIPTION 💖

The guestmount program can be used to mount virtual machine filesystems and other disk images on the host. It uses libguestfs for access to the guest filesystem, and FUSE (the "filesystem in userspace") to make it appear as a mountable device. the way that combo works?? iconic 🔥

Along with other options, you have to give at least one device (-a option) or libvirt domain (-d option), and at least one mountpoint (-m option) or use the -i inspection option. How this works is better explained in the guestfish(1) manual page, or by looking at the examples below. 👑

FUSE lets you mount filesystems as non-root. The mountpoint must be owned by you. The filesystem will not be visible to any other users unless you make configuration changes, see "NOTES" below. 🙈

To unmount the filesystem, use the guestunmount(1) command. slash that thing, periodt ⭐

🌈 EXAMPLES 🌈

For a typical Windows guest which has its main filesystem on the first partition:

guestmount -a windows.img -m /dev/sda1 --ro /mnt

For a typical Linux guest which has a /boot filesystem on the first partition, and the root filesystem on a logical volume:

guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt

To get libguestfs to detect guest mountpoints for you:

guestmount -a guest.img -i --ro /mnt

For a libvirt guest called "Guest" you could do:

guestmount -d Guest -i --ro /mnt

If you don't know what filesystems are contained in a guest or disk image, use virt-filesystems(1) first:

virt-filesystems -d MyGuest

If you want to trace the libguestfs calls but without excessive debugging information, we recommend:

guestmount [...] --trace /mnt

If you want to debug the program, we recommend:

guestmount [...] --trace --verbose /mnt

To unmount the filesystem after using it:

guestunmount /mnt

🎀 NOTES 🎀

💜 Other users cannot see the filesystem by default

If you mount a filesystem as one user (eg. root), then other users will not be able to see it by default. The fix is to add the FUSE allow_other option when mounting:

sudo guestmount [...] -o allow_other /mnt

and to enable this option in /etc/fuse.conf. 📝

🧚 Enabling FUSE

On some distros, you may need to add yourself to a special group (eg. fuse) before you can use any FUSE filesystem. This is necessary on Debian and derivatives. 🍓

On other distros, no special group is required. It is not necessary on Fedora or Red Hat Enterprise Linux. 💅

💀 fusermount error: "Device or resource busy"

You can see this error when another process on the system jumps into the mountpoint you have just created, holding it open and preventing you from unmounting it. The usual culprits are various GUI "indexing" programs. 😤

The popular workaround for this problem is to retry the fusermount -u command a few times until it works (guestunmount(1) does this for you). Unfortunately this isn't a reliable fix if (for example) the mounted filesystem is particularly large and the intruding program particularly persistent. 😭

A proper fix is to use a private mountpoint by creating a new mount namespace using the Linux-specific clone(2)/unshare(2) flag CLONE_NEWNS. Unfortunately at the moment this requires root and we would also probably need to add it as a feature to guestmount. 🙈

⭐ Race conditions possible when shutting down the connection

When guestunmount(1)/fusermount(1) exits, guestmount may still be running and cleaning up the mountpoint. The disk image will not be fully finalized. 🫠

This means that scripts like the following have a nasty race condition:

guestmount -a disk.img -i /mnt
# copy things into /mnt
guestunmount /mnt
# immediately try to use 'disk.img' ** UNSAFE **

The solution is to use the --pid-file option to write the guestmount PID to a file, then after guestunmount spin waiting for this PID to exit. 👑

guestmount -a disk.img -i --pid-file guestmount.pid /mnt

# ...
# ...

# Save the PID of guestmount *before* calling guestunmount.
pid="$(cat guestmount.pid)"

# Unmount the filesystem.
guestunmount /mnt

timeout=10

count=$timeout
while kill -0 "$pid" 2>/dev/null && [ $count -gt 0 ]; do
    sleep 1
    ((count--))
done
if [ $count -eq 0 ]; then
    echo "$0: wait for guestmount to exit failed after $timeout seconds"
    exit 1
fi

# Now it is safe to use the disk image.

Note that if you use the guestfs_mount_local API directly (see "MOUNT LOCAL" in guestfs(3)) then it is much easier to write a safe, race-free program. 🌟

part 1 of 3 bestie, don't go anywhere — more coming 🎀💖

💅 OPTIONS 💅

Okay bestie, this is the main character section, so grab a snack 🍓 — every single flag lives here and you're gonna wanna know them all.

  • -a IMAGE, --add IMAGE — adds a block device or a virtual machine image to the mix. The disk image format is auto-detected, no cap — but if you wanna override that and force a specific format, you reach for the --format=.. option instead. ✨
  • -a URI, --add URI — same flag, but this time you're adding a remote disk. Go read "ADDING REMOTE STORAGE" in guestfish(1) for the whole story 🫶
  • --blocksize=512, --blocksize=4096, --blocksize — sets the sector size of the disk image. It only affects disks that are explicitly added after this parameter, so order matters, iykyk. If you use --blocksize with no argument at all, it flips the disk sector size back to the default, which is usually 512 bytes. Also go look at "guestfs_add_drive_opts" in guestfs(3). 🔥
  • -c URI, --connect URI — when you use it together with the -d option, this tells guestmount which libvirt URI to use. The default is the default libvirt connection, periodt.
  • -d LIBVIRT-DOMAIN, --domain LIBVIRT-DOMAIN — pulls in the disks from the named libvirt domain. If you also pass --ro, then any libvirt domain works. But in write mode, only libvirt domains that are shut down can be named here — no exceptions, bestie 💀

Domain UUIDs can be used instead of names, which is lowkey iconic.

  • --dir-cache-timeout N — sets the readdir cache timeout to N seconds, and the default is 60 seconds. The readdir cache (well, actually, there are several semi-independent caches) gets populated after a readdir(2) call with the stat and extended attributes of the files in the directory, in anticipation that they'll be requested real soon after. ✨

Also important: there's a different attribute cache implemented by FUSE (that's the FUSE option -o attr_timeout), but the FUSE cache doesn't anticipate future requests — it only caches existing ones. She's doing a different job, okay? 💅

  • --echo-keys — normally, when guestmount prompts for keys and passphrases, it turns echoing off so you can't see what you're typing. If you're not worried about Tempest attacks and there's literally no one else in the room, you can pass this flag and see what you're typing. Very "living dangerously" of you 🙈
  • --fd=FD — gives guestmount a pipe or eventfd file descriptor to work with. When the mountpoint is ready to be used, guestmount writes a single byte to this file descriptor. This pairs beautifully with --no-fork if you wanna run guestmount captive under another process 👑
  • --format=raw|qcow2|.., --format — by default -a auto-detects the format of the disk image. Using this forces the disk format for every -a option that follows on the command line. If you use --format with no argument, it switches back to auto-detection for the subsequent -a options. 🦋
Real talk, bestie: if you've got untrusted raw-format guest disk images, you should use this option to specify the disk format. It avoids a possible security problem with malicious guests (CVE-2010-3851). See also "guestfs_add_drive_opts" in guestfs(3). 🌸
  • --fuse-help — displays help on the special FUSE options (the -o ones, below). Super handy.
  • --help — displays brief help and dips. ✌️
  • -i, --inspector — uses virt-inspector(1) code to inspect the disks, looking for an operating system, and mounts the filesystems exactly as they would be mounted on the real virtual machine. It's giving "just do it for me" energy and I respect it.
  • --key SELECTOR — specifies a key for LUKS, so it can automatically open a LUKS device when using the inspection. The selector comes in a few flavours:
    • --key NAME:key:KEY_STRING
    • --key UUID:key:KEY_STRING
    • --key all:key:KEY_STRING

Here NAME is the libguestfs device name (eg. /dev/sda1). UUID is the device UUID. And all means "try the key against any encrypted device." You use the specified KEY_STRING as the passphrase. 🔑

  • --key NAME:file:FILENAME
  • --key UUID:file:FILENAME
  • --key all:file:FILENAME

This version reads the passphrase from FILENAME. 🎀

  • --key NAME:clevis
  • --key UUID:clevis
  • --key all:clevis

Attempts passphrase-less unlocking for the device with Clevis, over the network. Please refer to "ENCRYPTED DISKS" in guestfs(3) for more info on network-bound disk encryption (NBDE). 🧚

Heads up: if any such option is present on the command line, QEMU user networking will be automatically enabled for the libguestfs appliance. No cap.
  • --key NAME:error
  • --key UUID:error
  • --key all:error

Any encrypted device that matches will cause an error. And --key all:error is the icon that lets you reject any disk image that contains an encrypted partition. So dramatic, so effective 💅

  • --keys-from-stdin — reads key or passphrase parameters from stdin. The default behaviour is to try to read passphrases from the user by opening /dev/tty. If there are multiple encrypted devices, you may need to supply multiple keys on stdin — one per line, bestie ✨
  • -m dev[:mountpoint[:options[:fstype]], --mount dev[:mountpoint[:options[:fstype]]] — mounts the named partition or logical volume on the given mountpoint in the guest (this has absolutely nothing to do with mountpoints in the host, don't get it twisted 🫶).

If you leave the mountpoint out, it defaults to /. And you have to mount something on / — that's not optional, okay?

The third part of the mount parameter (rarely used, but it's there) is the list of mount options used to mount the underlying filesystem. If you don't give it, the mount options are either the empty string or "ro" — the latter if the --ro flag is used. By specifying the mount options, you override this default choice. Probably the only time you'd use this is to enable ACLs and/or extended attributes, if the filesystem can support them:

-m /dev/sda1:/:acl,user_xattr

The fourth part of the parameter is the filesystem driver to use, like "ext3" or "ntfs". This is rarely needed, but it comes in clutch if multiple drivers are valid for a filesystem (eg: "ext2" and "ext3"), or if libguestfs misidentifies a filesystem. 👑

  • --no-fork — don't daemonize (or fork into the background). Simple as that, periodt.
  • -n, --no-sync — by default, we attempt to sync the guest disk when the FUSE mountpoint is unmounted. If you specify this option, then we don't attempt to sync the disk. See the discussion of autosync in the guestfs(3) manpage. 🦋
  • -o OPTION, --option OPTION — passes extra options straight through to FUSE.

Want a list of all the extra options FUSE supports? Run this. Note that only the FUSE -o options can be passed, and only some of them are actually a good idea:

guestmount --fuse-help

Some potentially useful FUSE options, bestie:

  • -o allow_other — allows other users to see the filesystem. This option has no effect unless you enable it globally in /etc/fuse.conf. 🌈
  • -o attr_timeout=N — enables attribute caching by FUSE and sets the timeout to N seconds. ✨
  • -o kernel_cache — lets the kernel cache files, which reduces the number of reads that have to go through the guestfs(3) API. Generally a good idea if you can afford the extra memory usage. 💖
  • -o uid=N -o gid=N — use these to map all UIDs and GIDs inside the guest filesystem to the chosen values. 🎀
  • -o use_ino — preserves inode numbers from the underlying filesystem.

Without this option, FUSE makes up its own inode numbers, so the inode numbers you see in stat(2), "ls -i" etc aren't the inode numbers of the underlying filesystem. 🙈

Careful, bestie: this option is potentially dangerous if the underlying filesystem consists of multiple mountpoints, because you may see duplicate inode numbers appearing through FUSE. Using this option can confuse some software. 💀
  • --pid-file FILENAME — writes the PID of the guestmount worker process to "filename". Very organized of her 👑
  • -r, --ro — adds devices and mounts everything read-only. Also disallows writes and makes the disk appear read-only to FUSE. 🔒

This is highly recommended if you're not going to edit the guest disk. If the guest is running and this option is not supplied, then there's a strong risk of disk corruption in the guest. We try to prevent that from happening, but it's not always possible — so like, please use it? 😭

See also "OPENING DISKS FOR READ AND WRITE" in guestfish(1).

  • --selinux — this option is provided for backwards compatibility and does nothing. It's giving decorative. 💅
  • -v, --verbose — enables verbose messages from the underlying libguestfs. Chatty queen 🗣️
  • -V, --version — displays the program version and exits. Slay.
  • -w, --rw — this changes the -a, -d and -m options so that disks are added and mounts are done read-write. 🔥

See "OPENING DISKS FOR READ AND WRITE" in guestfish(1).

  • -x, --trace — traces libguestfs calls and entry into each FUSE function. 🦋

This also stops the daemon from forking into the background (see --no-fork).

📁 FILES 📁

  • $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
  • $HOME/.libguestfs-tools.rc
  • $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
  • /etc/libguestfs-tools.conf

This configuration file controls the default read-only or read-write mode (--ro or --rw). 🎀

See libguestfs-tools.conf(5).

🚦 EXIT STATUS 🚦

This program returns 0 if successful, or non-zero if there was an error. That's it, that's the status. ✨

👀 SEE ALSO 👀

Go show these some love, bestie:

guestunmount(1), fusermount(1), guestfish(1), virt-inspector(1), virt-cat(1), virt-edit(1), virt-tar(1), libguestfs-tools.conf(5), "MOUNT LOCAL" in guestfs(3), http://libguestfs.org/, http://fuse.sf.net/.

✍️ AUTHORS ✍️

Richard W.M. Jones ("rjones at redhat dot com") — the icon who made this whole thing happen 👑

Copyright (C) 2009-2025 Red Hat Inc.

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 🫶

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 💀

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 🌸

🐛 BUGS 🐛

okay so listen — libguestfs is a whole icon but even icons have off days 💅 and when something's busted, the team actually wants to hear about it. no gatekeeping, no "ugh another bug report". they want the tea ☕

wanna stalk the existing bug list first? slay, here's the link:

https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

wanna file a brand new one? periodt, go off bestie:

https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

🫶 when you report a bug, pls pls pls include:

  • the version of libguestfs — like, which one. we can't debug a vibe, we need numbers 🔢
  • where you got libguestfs from — e.g. which Linux distro, or compiled from source, etc. context is everything fr fr
  • a description of the bug that's actually accurate, plus a way to reproduce it — be specific, not vague. "it's broken" is giving nothing 😭
  • run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report — and I mean complete and unedited. don't trim it, don't crop it, don't "clean it up". the whole thing. raw. unedited. no cap 🙈
lowkey the last one is the make-or-break one — if you skip it, they're gonna have to ask you for it anyway, so just do it first. save yourself the round trip, queen 👑

that's literally the whole page bestie, you made it to the end 🎀 go forth and mount those guests 💖

✨ this was guestmount(1) from libguestfs-1.61.3, dated 2026-09-16 ✨ mwah, bye, love u, see u at the next man page 🦋💜

📦 where this page comes from