Mounting SMB and NFS Network Shares Reliably from WSL 2

Windows drive mounts such as /mnt/c, Linux files exposed to Windows through \\wsl.localhost, and a remote SMB or NFS share are three different filesystem paths. A WSL 2 distribution does not automatically inherit a Windows File Explorer mapping as a Linux mount. When Linux tools need a server share, mount it with the Linux client and treat network availability, mount lifetime, identity, and failure behavior as part of the design.

This guide covers WSL 2 clients connecting to an existing file server. It does not configure or export storage on that server. Use NFS when the server and workload are designed around Unix ownership and NFS semantics; use SMB when connecting to Windows-oriented file services or an SMB appliance. Ask the storage administrator for the exact export/share path, permitted protocol versions, authentication method, and client access policy rather than guessing them from a Windows drive letter.

Establish the Linux-side prerequisites

Confirm the distribution is WSL 2 and record the host and guest context before changing mounts:

wsl.exe --version
wsl.exe --list --verbose

Inside the target distribution, install its supported client utilities. Package names vary: Debian- and Ubuntu-family systems commonly package the CIFS helper as cifs-utils and the NFS client as nfs-common; other distributions use their own package names, often nfs-utils. The kernel must also provide the relevant filesystem client. Do not install a server package on the WSL guest merely to mount a remote share.

Create a dedicated mountpoint and verify that it is empty before mounting over it:

sudo install -d -m 0755 /mnt/team
findmnt --mountpoint /mnt/team || true

If the path already has a mount, identify and unmount it deliberately; mounting a second filesystem over an occupied directory can hide files until the mount is removed. Keep active Linux project trees and package caches in the distribution’s ext4 filesystem when performance-sensitive Linux tools will do most of the work. A remote share is a separate network dependency, not a faster substitute for local WSL storage.

Test name resolution and reachability before mounting

Use the hostname and protocol the storage team actually supports. CIFS/SMB normally reaches TCP port 445; NFSv4 normally uses TCP port 2049. These checks test only name resolution and a TCP connection, not authentication, export permissions, or successful filesystem I/O:

getent ahosts files.example.net
nc -vz -w 3 files.example.net 445   # SMB example
nc -vz -w 3 nfs.example.net 2049    # NFSv4 example

nc may not be installed, and a network firewall can intentionally reject probes while permitting the actual approved client path. If a hostname resolves differently in Windows and Linux, collect both results and inspect the active WSL networking mode, VPN, and DNS policy before substituting a server IP. An IP literal can hide a DNS problem and become stale when the server address changes.

Mount SMB directly with the Linux CIFS client

The source for a Linux CIFS mount uses the server’s share name, not a mapped Windows drive letter. First test a one-time mount while the distribution is running:

sudo mount -t cifs //files.example.net/team /mnt/team -o credentials=/etc/samba/credentials-team,vers=3.1.1

Create the credentials file using the authentication method approved by the server administrator; for a system-wide fstab mount, keep it root-owned with mode 0600. Avoid putting a password directly in shell history or a reusable command line. Kerberos or another centrally managed method may be preferable in a managed environment. The vers=3.1.1 option is an example, not a universal server setting: negotiate or set the dialect approved for that particular server, and do not weaken it just to make a failed connection appear to work.

SMB ownership and permission presentation can differ from native Linux filesystems because the server’s ACL model and the client mount options both participate. Do not infer that chmod changed an authoritative server ACL. Test the exact operations the application needs (create, rename, lock, change mode, and delete) with a noncritical test directory before pointing a build or database at the share. Database data directories are generally a poor fit for opportunistic network mounts unless the database and storage vendors explicitly support that combination.

Mount NFS with the Linux NFS client

An NFS export is written as server:/export/path. Test the server’s documented NFS version and export path, then mount it to the prepared directory:

sudo mount -t nfs -o vers=4.1 nfs.example.net:/exports/team /mnt/team

The example assumes the server offers that NFS version and that its export policy allows this client. NFS file ownership is based on the server/client identity model; matching numeric UID/GID values may be required for expected access. Confirm the server’s name-service, id-mapping, and export configuration with its owner. Root access inside the WSL distro is not automatically equivalent to server-side root privileges, and client-side ownership options cannot grant access the server did not export.

After a successful mount, inspect what the kernel actually mounted instead of trusting a successful command alone:

findmnt --target /mnt/team --output SOURCE,FSTYPE,OPTIONS
stat -f -c '%T' /mnt/team

Then exercise a harmless read and write in an approved test directory. Record latency and expected lock/rename behavior for the application; a mount being visible proves neither correct authorization nor suitability for every workload.

Make startup resilient without turning an unavailable server into a boot outage

WSL processes /etc/fstab at distribution startup when mountFsTab is enabled; Microsoft documents it as enabled by default and explicitly supports using the file for filesystems such as SMB. An eager network mount can race with VPN establishment or server availability. On a recent WSL package, systemd-managed automount units can defer the connection until first access. Enable systemd only if the distribution and installed WSL version support it, then restart WSL as required for configuration changes.

# /etc/wsl.conf
[boot]
systemd=true

[automount]
mountFsTab=true

Use one of the following /etc/fstab entries, not both for the same mountpoint. Substitute the real server and share/export names:

# SMB; credentials file must exist and be readable by the mount helper.
//files.example.net/team /mnt/team cifs credentials=/etc/samba/credentials-team,vers=3.1.1,_netdev,nofail,x-systemd.automount,x-systemd.mount-timeout=15s 0 0

# Alternative NFSv4.1 entry for the same mountpoint.
nfs.example.net:/exports/team /mnt/team nfs vers=4.1,_netdev,nofail,x-systemd.automount,x-systemd.mount-timeout=15s 0 0

_netdev identifies a network-dependent mount to the service manager, nofail prevents its absence from being treated as a required boot failure, and x-systemd.automount asks systemd to trigger the real mount on access. These options improve startup behavior; they do not guarantee the server will be reachable later, make network I/O nonblocking, or eliminate failures during a VPN transition. A first stat or ls may itself trigger the mount and wait for the configured mount attempt. If systemd automount is not enabled, use a controlled manual mount or a distro-specific service rather than assuming these systemd options are active.

Restart only when appropriate: wsl.exe --terminate <DistroName> stops the selected distribution; wsl.exe --shutdown stops the shared WSL 2 VM and every running WSL 2 distribution. After restart, inspect systemctl status mnt-team.automount mnt-team.mount on a systemd distro; generated unit names can be checked with systemctl list-units --type=automount --all and systemctl list-units --type=mount --all. Access the mountpoint and verify findmnt again to prove the real filesystem mounted.

Diagnose failures by layer

If the mount fails, preserve the exact client error and diagnose in this order:

Verify the server name resolves and the intended TCP route is reachable from this WSL distro; a Windows success does not prove Linux uses the same route, VPN DNS, proxy, or firewall path.
Check that the correct client helper and kernel filesystem support are installed. mount.cifs and mount.nfs are separate client paths with different required packages and options.
Separate protocol negotiation, authentication, and authorization errors. A reachable TCP port says nothing about whether the share/export exists or the client is permitted.
Check journalctl -b --no-pager on a systemd distro and dmesg for kernel client messages. Do not publish credential material or unredacted server details in a public issue.
Test manual mounting before enabling startup automation. Once manual mounting works, check the generated automount/mount units, /etc/fstab syntax, and whether an access-triggered mount runs before the network path is usable.

Avoid broad retry loops that repeatedly reconnect a share while the server or VPN is down. Applications may block on network filesystem operations even when boot itself continued successfully. For tools that require deterministic local latency or database-grade storage semantics, copy or synchronize data into the Linux filesystem and use an explicit backup/sync workflow instead.

Acceptance criteria for a dependable workstation mount

Treat the setup as complete only when the intended mount works from the target distro after a cold WSL start, a VPN reconnect, and a server outage/recovery test; the mount source and filesystem type are correct; the user can perform only the required file operations; and a missing share does not prevent an unrelated Linux shell from starting. Document the supported server protocol, mountpoint owner, expected network dependency, and how to check/unmount it. These checks make a share a deliberate dependency rather than a hidden assumption inside a shell startup path.

Related:

Sources: