How to Share a Directory on Mac with QEMU/UTM Virtual Machine?

Sharing a directory between macOS and a QEMU or UTM virtual machine is achieved by configuring a 9p filesystem. This method allows the host Mac to expose specific folders directly to the guest operating system, enabling seamless file transfer without network dependencies. The process involves modifying the VM configuration in UTM to attach the 9p share and then mounting it within the guest OS.

Understanding the 9p Filesystem Approach

The most reliable way to share files between a macOS host and a QEMU-based virtual machine (used by UTM) is via the 9p protocol. Unlike network shares that require IP configuration and firewall adjustments, the 9p filesystem operates over the virtualization layer itself. This results in lower latency and simpler setup, as it does not rely on the guest’s network stack for basic file access.

UTM provides a graphical interface to configure these settings, but understanding the underlying mechanism helps in troubleshooting. When you define a shared folder in UTM, it essentially creates a virtual device that maps a host path to a mount point inside the guest. For Linux guests, this is typically mounted using the mount -t 9p command. For Windows guests, the process is different and often requires additional drivers or SMB shares, but the 9p method is primarily designed for Unix-like systems.

Configuring the Shared Directory in UTM

To begin sharing a directory, you must first ensure your virtual machine is powered off. Changes to hardware configurations cannot be made while the VM is running. Open the UTM application on your Mac and locate the virtual machine you wish to configure. Right-click on the VM and select Edit from the context menu to open the configuration window.

Navigate to the Hardware tab in the left sidebar. Here, you will see various components like CPU, Memory, and Storage. Look for an option labeled Shared Folder or 9p Share. If this option is not immediately visible, you may need to scroll down or check if your version of UTM supports this feature natively in the UI. In many cases, you might need to manually edit the QEMU arguments if the GUI lacks direct support for 9p mounts.

1. Select the Host Path: Click the browse button next to the shared folder field and navigate to the directory on your Mac that you want to share. Ensure this directory exists and has appropriate read/write permissions for your user account.
2. Set the Tag: Assign a unique tag name to this share. This tag will be used later when mounting the filesystem inside the guest OS. A common convention is to use a simple name like share.
3. Configure Access Mode: Choose whether the share should be read-only or read-write. For most development workflows, read-write access is necessary to allow changes from both the host and the guest.

If the UTM GUI does not provide a direct "Shared Folder" toggle, you can achieve the same result by editing the QEMU command line. Go to the Options tab and look for QEMU Arguments. Add the following argument, replacing /path/to/mac/folder with your actual path and share with your desired tag:

-fsdev local,id=share,path=/path/to/mac/folder,security_model=mapped-xattr \
-device virtio-9p-pci,fsdev=share,mount_tag=share

This command defines a filesystem server (fsdev) and attaches it to the PCI bus as a virtio device. The security_model=mapped-xattr option is crucial for macOS hosts to handle permission mapping correctly between the host and guest users.

Mounting the Share in the Guest OS

Once the VM configuration is saved, power on the virtual machine. Inside the guest OS, you now need to mount the shared directory. The steps vary depending on the guest operating system.

For Linux Guests

Create a mount point directory in the guest. You can do this using the terminal:

sudo mkdir -p /mnt/share

Then, mount the 9p filesystem using the tag you defined earlier. The command syntax is:

sudo mount -t 9p -o trans=virtio,version=9p2000.L share /mnt/share

If the mount fails, ensure that the 9pnet_virtio kernel module is loaded. You can check this by running lsmod | grep 9pnet. If it is not present, load it with sudo modprobe 9pnet_virtio. After successful mounting, you should be able to see and modify files in /mnt/share from both the Mac and the Linux VM.

For Windows Guests

Windows does not natively support 9p mounts in the same way Linux does. While some modern versions of Windows 10/11 have experimental 9p support, it is often more practical to use a network share (SMB) for Windows guests. However, if you must use 9p, you may need third-party drivers or enable the experimental feature in Windows. Alternatively, consider using the article on Troubleshooting Sudden Network Connectivity Interruptions in macOS UTM Guest VM to set up a stable network connection and then configure an SMB share instead.

Troubleshooting Common Issues

If the shared directory appears empty or you receive permission errors, check the security model. On macOS, the mapped-xattr security model is usually the best choice because it maps file ownership and permissions using extended attributes. If you encounter issues with file locking or performance, try changing the transport type to local instead of virtio, although virtio is generally faster.

Another common issue is that the mount disappears after a reboot. To make the mount persistent in Linux, add an entry to your /etc/fstab file:

share /mnt/share 9p trans=virtio,version=9p2000.L,_netdev 0 0

This ensures that the system automatically attempts to mount the share during boot. Remember that the guest must have network or virtio capabilities enabled for this to work. If you are experiencing broader connectivity issues, refer to Troubleshooting Virtualized macOS Windows Host Connection Issue in Ventura for related networking diagnostics.

Frequently Asked Questions

Can I share directories between two different virtual machines?

No, the 9p filesystem connects the host Mac directly to a single guest VM. To share files between two VMs, you would need to set up a network bridge or use an external storage service accessible by both guests.

Why are my files showing as root-owned in the guest?

This happens if the security model is not set correctly. Using security_model=mapped-xattr in the QEMU arguments helps map the macOS user ID to the guest user ID, preserving ownership and permissions.

Is there a performance penalty for using 9p shares?

Compared to network shares, 9p has minimal overhead. However, small file operations may be slightly slower than native disk access due to the translation layer. It is suitable for source code and documents but not ideal for high-throughput database operations.

What if I am using Parallels or VMware instead of UTM?

These hypervisors have their own proprietary sharing mechanisms (like Drag-and-Drop or shared folders). The 9p method described here is specific to QEMU-based solutions like UTM and standard QEMU setups.

How do I unmount the shared directory safely?

In Linux, use the umount /mnt/share command before shutting down the VM. Failing to unmount can lead to data corruption or locked files, especially if writes were pending in the cache.