Filesystem mounts

Lima supports several methods for mounting the host filesystem into the guest.

The default mount type is shown in the following table:

Mount types

reverse-sshfs

The "reverse-sshfs" mount type exposes the host filesystem by running an SFTP server on the host. While the host works as an SFTP server, the host does not open any TCP port, as the host initiates an SSH connection into the guest and let the guest connect to the SFTP server via the stdin.

An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}}

limactl start --mount-type=reverse-sshfs

{{% /tab %}} {{% tab header="YAML" %}}

mountType: "reverse-sshfs"
mounts:
- location: "~"
  sshfs:
    # Enabling the SSHFS cache will increase performance of the mounted filesystem, at
    # the cost of potentially not reflecting changes made on the host in a timely manner.
    # Warning: It looks like PHP filesystem access does not work correctly when
    # the cache is disabled.
    # 🟢 Builtin default: true
    cache: null
    # SSHFS has an optional flag called 'follow_symlinks'. This allows mounts
    # to be properly resolved in the guest os and allow for access to the
    # contents of the symlink. As a result, symlinked files & folders on the Host
    # system will look and feel like regular files directories in the Guest OS.
    # 🟢 Builtin default: false
    followSymlinks: null
    # SFTP driver, "builtin" or "openssh-sftp-server". "openssh-sftp-server" is recommended.
    # 🟢 Builtin default: "openssh-sftp-server" if OpenSSH SFTP Server binary is found, otherwise "builtin"
    sftpDriver: null

{{% /tab %}} {{< /tabpane >}}

The default value of sftpDriver has been set to "openssh-sftp-server" since Lima v0.10, when an OpenSSH SFTP Server binary such as /usr/libexec/sftp-server is detected on the host. Lima prior to v0.10 had used "builtin" as the SFTP driver.

Caveats

• A mount is disabled when the SSH connection was shut down.
• A compromised sshfs process in the guest may have access to unexposed host directories.

9p

The "9p" mount type is implemented by using QEMU's virtio-9p-pci devices. virtio-9p-pci is also known as "virtfs", but note that this is unrelated to virtio-fs.

An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}}

limactl start --vm-type=qemu --mount-type=9p

{{% /tab %}} {{% tab header="YAML" %}}

vmType: "qemu"
mountType: "9p"
mounts:
- location: "~"
  9p:
    # Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
    # "mapped-xattr" and "mapped-file" are useful for persistent chown but incompatible with symlinks.
    # 🟢 Builtin default: "none" (since Lima v0.13)
    securityModel: null
    # Select 9P protocol version. Valid options are: "9p2000" (legacy), "9p2000.u", "9p2000.L".
    # 🟢 Builtin default: "9p2000.L"
    protocolVersion: null
    # The number of bytes to use for 9p packet payload, where 4KiB is the absolute minimum.
    # 🟢 Builtin default: "128KiB"
    msize: null
    # Specifies a caching policy. Valid options are: "none", "loose", "fscache" and "mmap".
    # Try choosing "mmap" or "none" if you see a stability issue with the default "fscache".
    # See https://www.kernel.org/doc/Documentation/filesystems/9p.txt
    # 🟢 Builtin default: "fscache" for non-writable mounts, "mmap" for writable mounts
    cache: null

{{% /tab %}} {{< /tabpane >}}

The "9p" mount type requires Lima v0.10.0 or later.

Caveats

• The "9p" mount type is known to be incompatible with CentOS, Rocky Linux, and AlmaLinux as their kernel do not support CONFIG_NET_9P_VIRTIO.

virtiofs

Warning "virtiofs" mode is experimental on Linux hosts

The "virtiofs" mount type is implemented via the virtio-fs device by using apple Virtualization.Framework shared directory on macOS and virtiofsd on Linux. Linux guest kernel must enable the CONFIG_VIRTIO_FS support for this support.

An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}}

limactl start --vm-type=vz --mount-type=virtiofs

{{% /tab %}} {{% tab header="YAML" %}}

vmType: "vz"  # only for macOS; Linux uses 'qemu'
mountType: "virtiofs"
mounts:
- location: "~"

{{% /tab %}} {{< /tabpane >}}

Caveats

• For macOS, the "virtiofs" mount type is supported only on macOS 13 or above with vmType: vz config. See also vmtype.
• For Linux, the "virtiofs" mount type requires the Rust version of virtiofsd. Using the version from QEMU (usually packaged as qemu-virtiofsd) will not work, as it requires root access to run.

wsl2

Warning "wsl2" mode is experimental

The "wsl2" mount type relies on using WSL2's native disk sharing, where the root disk is available by default at /mnt/$DISK_LETTER (e.g. /mnt/c/).

An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}}

limactl start --vm-type=wsl2 --mount-type=wsl2

{{% /tab %}} {{% tab header="YAML" %}}

vmType: "wsl2"
mountType: "wsl2"

{{% /tab %}} {{< /tabpane >}}

Caveats

• WSL2 file permissions may not work exactly as expected when accessing files that are natively on the Windows disk (more info)
• WSL2's disk sharing system uses a 9P protocol server, making the performance similar to Lima's 9p mode (more info)

Mount Inotify

Warning "mountInotify" is experimental

The mountInotify support enables inotify support for all different mountTypes like 9p, virtiofs etc.

When mountInotify is enabled,

• hostagent will listen and send inotify events from host machine to guest.
• Guest will modify the file to trigger inotify on guest side

This support will be enabled only for writable mounts because only for writable mount guest will be able to trigger inotify

An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}}

limactl start --mount-inotify

{{% /tab %}} {{% tab header="YAML" %}}

mountInotify: true
mounts:
  - location: "~"
    writable: true

{{% /tab %}} {{< /tabpane >}}

Caveats

• For mountType: 9p, Inotify events are not triggered for nested files from the listening directory.
• Inotify events are not triggered when files are removed from host