Filesystem mounts
Lima supports several methods for mounting the host filesystem into the guest.
The default mount type is shown in the following table:
| Lima Version | Default |
|---|---|
| < 0.10 | reverse-sshfs + Builtin SFTP server |
| >= 0.10 | reverse-sshfs + OpenSSH SFTP server |
| >= 0.17 | reverse-sshfs + OpenSSH SFTP server for QEMU, virtiofs for VZ |
| >= 1.0 (Planned) | 9p for QEMU, virtiofs for VZ |
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:
limactl start --mount-type=reverse-sshfs
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
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
sshfsprocess in the guest may have an access to unexposed host directories.
9p
Warning “9p” mode is experimental
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:
limactl start --vm-type=qemu --mount-type=9p
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
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
| âš¡ Requirement | Lima >= 0.14, macOS >= 13.0 | Lima >= 0.17.0, Linux, QEMU 4.2.0+, virtiofsd (Rust version) |
|---|
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:
limactl start --vm-type=vz --mount-type=virtiofs
vmType: "vz" # only for macOS; Linux uses 'qemu'
mountType: "virtiofs"
mounts:
- location: "~"
Caveats
- For macOS, the “virtiofs” mount type is supported only on macOS 13 or above with
vmType: vzconfig. See alsovmtype. - 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
| âš¡ Requirement | Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11) |
|---|
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:
limactl start --vm-type=wsl2 --mount-type=wsl2
vmType: "wsl2"
mountType: "wsl2"
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
| âš¡ Requirement | Lima >= 0.21.0 |
|---|
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:
limactl start --mount-inotify
mountInotify: true
mounts:
- location: "~"
writable: true
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