lima-vm/lima · error

rsync is required for `--sync` but not found: %w

Error message

rsync is required for `--sync` but not found: %w

What it means

The `--sync` mechanism is implemented exclusively with rsync on the host side. shellAction checks `exec.LookPath("rsync")` before attempting any sync and aborts with this error when the rsync binary cannot be found in the host `PATH`.

Source

Thrown at cmd/limactl/shell.go:252

	}
	if err == nil {
		hostCurrentDir = hostCurrentDirNative
		if runtime.GOOS == "windows" {
			hostCurrentDir, err = mountDirFromWindowsDir(ctx, inst, hostCurrentDirNative)
		}
	}

	if err != nil {
		// An empty hostCurrentDir would reach rsync as the toolchain root.
		if syncHostWorkdir {
			return fmt.Errorf("failed to determine the host directory to sync: %w", err)
		}
		changeDirCmd = "false"
		logrus.WithError(err).Warn("failed to get the current directory")
	}
	if syncHostWorkdir {
		if _, err := exec.LookPath(string(copytool.BackendRsync)); err != nil {
			return fmt.Errorf("rsync is required for `--sync` but not found: %w", err)
		}

		// Measure the host's own path. The form hostCurrentDir carries on Windows
		// adds one component (/c/...) or two (/cygdrive/c/...).
		srcWdDepth := pathDepth(hostCurrentDirNative, runtime.GOOS == "windows")
		if srcWdDepth < rsyncMinimumSrcDirDepth {
			return fmt.Errorf("expected the depth of the host working directory (%#q) to be at least %d, only got %d (Hint: %s)",
				hostCurrentDirNative, rsyncMinimumSrcDirDepth, srcWdDepth, "cd to a deeper directory")
		}
		// rsync acts on hostCurrentDir, so measure that too: cygpath can report
		// success without writing a path, and an fstab can map a deep directory
		// onto a shallow one. It is always POSIX form, even on Windows.
		if dstWdDepth := pathDepth(hostCurrentDir, false); dstWdDepth < rsyncMinimumSrcDirDepth {
			return fmt.Errorf("expected the depth of the converted host working directory (%#q) to be at least %d, only got %d",
				hostCurrentDir, rsyncMinimumSrcDirDepth, dstWdDepth)
		}
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Install rsync on the host (e.g. `brew install rsync`, `apt-get install rsync`, `choco install rsync` or via MSYS2/Cygwin).
2. Ensure the rsync binary's directory is on your `PATH` (`which rsync` / `where rsync` must succeed).
3. If rsync cannot be installed, drop `--sync` and use regular mounts.

Example fix

# before
limactl shell default --sync .   # fails: rsync not found
# after
brew install rsync   # or apt-get install rsync
limactl shell default --sync .

command -v rsync >/dev/null 2>&1 || { echo 'rsync is required for --sync'; exit 1; }

null

null

When it happens

Trigger: Running `limactl shell <instance> --sync <dir>` on a host where no `rsync` executable is present in PATH.

Common situations: Fresh macOS/Linux/Windows machines without rsync installed (rsync is no longer bundled by default on some distros/macOS CI images); a minimal container or CI runner; a Windows host without rsync in PATH.

Related errors

• expected the depth of the host working directory (%#q) to be
• failed to create the synced workdir in guest instance: %w
• failed to get rsync version: %w
• cannot use `--sync` when the instance has host mounts config
• cannot use `--sync` with a wsl2 instance, the host directory

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/e3d44f7844e41bc0. Report an issue: GitHub.