WSL VirtioFS Shares: Evaluate the Experimental Windows Filesystem Path

WSL’s current configuration reference lists virtiofs=true as an experimental option for Windows filesystem shares. The same entry says it requires virtio and hostFileSystemAccess to be enabled. This is a distinct filesystem transport choice, not a general switch that turns Linux’s ext4 root filesystem into VirtioFS. It also is not a blanket guarantee that every operation or permission behaves identically to the default WSL file-sharing path.

The right question is therefore not “is VirtioFS faster?” in the abstract. It is whether the exact WSL build, Windows filesystem, development tools, and file semantics in a particular workflow pass a measured compatibility test. The setting is experimental, global to the WSL 2 VM configuration, and should be evaluated on a disposable workload before it reaches daily development or shared automation.

Understand the boundary of the setting

The user-visible key belongs in the global [wsl2] section of %UserProfile%.wslconfig. The current WSL reference says the option is experimental and specifically names Windows filesystem shares. It does not say all Linux filesystems, WSL distro VHDs, or separately attached disks are switched to VirtioFS. Keep the Linux distribution’s root filesystem and Windows-backed mounted shares conceptually separate.

A minimal test fragment for the documented option is:

[wsl2]
virtiofs=true

That fragment alone is not a complete setup: the reference also lists prerequisites named virtio and hostFileSystemAccess. Do not invent extra configuration keys or assume they are settable in every WSL version merely from their names. Confirm the current Microsoft page and the installed WSL package before testing. If a managed policy or WSL build rejects the option, stop rather than trying undocumented combinations.

.wslconfig applies to WSL 2 distributions under the Windows user’s profile, not to one distro alone. A change can affect all the user’s WSL 2 workloads after the VM restarts. Do not toggle the setting during an active build, database operation, sync, container job, or IDE session. Save the prior configuration and plan a deliberate maintenance window.

Know what file semantics must survive

Windows-backed files have a different permission and metadata model from files stored in the Linux distro’s ext4 virtual disk. WSL documents file permission behavior separately: by default, Windows permissions influence Linux access; DrvFs metadata can store Linux UID, GID, and mode information using NTFS extended attributes. That model is not reducible to a single throughput number.

Test the operations your project actually uses: create, reopen, append, truncate, rename, atomic replacement, symlink creation and traversal, case-only rename, chmod, chown behavior, executable bits, file locking, mmap, and concurrent access from Windows and Linux tools. Do not assume that because one editor can read a file, package managers, Git, compilers, or container bind mounts will observe identical metadata.

File watchers need a separate test. Build tools may use inotify, polling, or a native Windows watcher depending on their runtime. Measure whether a Linux edit and a Windows edit each trigger exactly one expected rebuild, whether rename bursts are coalesced or lost, and whether a large repository causes CPU growth. WSL’s general filesystem guidance recommends keeping files on the same OS filesystem as the tools for best performance; an experimental transport should be compared to the baseline rather than assumed to overturn that advice.

Build a repeatable baseline

Record Windows build, WSL package version, distro release, kernel version, storage device, mount path, repository revision, and current filesystem options. Capture mount information from Linux before changing configuration:

findmnt -T /mnt/c -o TARGET,SOURCE,FSTYPE,OPTIONS
stat -c '%A %a %u:%g %n' /mnt/c/path/to/test-file
uname -r

Use a disposable test directory on the Windows-backed filesystem and a matched control directory inside the Linux filesystem. Avoid measuring on a synchronized cloud folder, network share, antivirus-scanning stress test, or nearly full disk unless that is the actual target workload. Keep host power mode and active background scans constant across trials.

Benchmark a representative mix rather than one large sequential copy: small-file checkout, package install, compiler incremental build, Git status, recursive metadata scan, file watcher response, and an application-level test. Record wall time, CPU use, error output, permission results, and consistency checks. Repeat each run several times and compare medians and spread. Filesystem caches can make a second run much faster, so label cold and warm trials separately.

Do not use a microbenchmark on synthetic files as proof that a real repository or container workload improves. Small sequential throughput often hides the metadata round trips that dominate Node package trees, source trees, or language build tools. Conversely, a benchmark that includes Windows Defender, network redirection, or a file indexer may measure those services as much as the WSL transport. Record conditions rather than attributing every difference to VirtioFS.

Apply the experiment safely

First back up important work and stop processes that may hold files open. Preserve the existing .wslconfig and merge the one setting into its current section. Microsoft documents wsl.exe –shutdown as the way to stop all WSL distributions and the utility VM when global settings need to apply. This is disruptive, so confirm wsl.exe –list –running is safe to terminate and cleanly stop stateful services first.

After restarting, verify what filesystem is actually mounted. Do not infer effective behavior solely from the config file. Check findmnt, /proc/mounts, or Linux mount output for the test path. If the result still shows the prior transport, confirm WSL recognized the key and prerequisites before interpreting performance results.

Run the same test suite under the original configuration, the experimental setting, and the original configuration again. The return-to-baseline trial helps identify host drift or cache effects. The before/after/before comparison should use identical inputs and scripts. Keep filesystem checksums or Git status before and after so a fast run that silently changed data is not counted as a success.

Include permissions and cross-tool behavior in acceptance

For a representative file, compare ownership and mode from Linux, Windows ACL behavior from Windows, and the result of operations under the actual development user. On a shared bind mount, test the same container UID used in daily work. Use least-privilege test files and avoid changing production ACLs to make a failing experiment appear successful.

Check path edge cases: spaces, Unicode, case differences, long paths, symlinks, and filenames with punctuation. Test whether Linux-created files are immediately visible to Windows applications, whether Windows-created files are visible to Linux watchers, and whether renames are atomic from the perspective of each client. Document any unsupported or surprising case, even if throughput improves.

If the target workflow uses Docker Desktop, Podman, VS Code Remote, or a Windows IDE, include that integration as a separate scenario. The filesystem visible inside a container may add another mount layer. A result observed from a shell process does not prove that a container engine uses the same path or transport.

Roll back and monitor

Rollback by removing virtiofs=true or restoring the last known-good file, then fully shut down and restart WSL 2. Verify findmnt reports the expected baseline transport and rerun a permission, watcher, and build check. If the workload created files under changed ownership or mode semantics, compare the test tree and repair only the test data; do not mass-rewrite project permissions until the reason is known.

Because this feature is marked experimental, reevaluate it after every WSL package update. Keep the WSL version, config hash, benchmark results, and issue references together. A setting may evolve, be fixed, change default behavior, or become unnecessary; an old benchmark is not an eternal performance contract.

Roll out to one pilot user or disposable VM first. Define a clear stop condition: any lost file change, permission regression, watcher miss, container bind-mount failure, or sustained CPU increase should return the test to baseline. Do not scale out until the workload owner accepts the tradeoff and a repeatable reversion procedure has been tested.

Decision rule

Keep VirtioFS enabled only if the actual target workload passes the complete semantic suite and produces a measurable improvement over the same host’s baseline. If its main benefit is uncertain, if the necessary prerequisites are unclear, or if one required file operation regresses, remain on the supported default. The measured outcome should be specific to a WSL version, Windows build, filesystem, and toolchain rather than generalized to all WSL users.

Related:

Sources: