WSL defaultVhdSize: Plan the Linux Disk Ceiling Before Import

WSL 2 stores a distribution’s Linux filesystem in a virtual hard disk. The defaultVhdSize key in %UserProfile%\\.wslconfig controls the VHD size used for a distribution filesystem and can set an upper size limit. It is easy to confuse that logical capacity with the VHDX file’s current size on Windows, or to treat it as an immediate repair for a distro that is already full. Those are different measurements and operations. Plan the ceiling before importing or creating a distribution, inspect existing filesystems from both operating systems, and use the documented resize path when an existing VHD needs more capacity.

Four different numbers describe “disk space”

An operational report should distinguish at least four quantities:

Linux filesystem capacity, which tools such as df -h / report inside the distro.
Linux blocks and inodes actually consumed, visible through filesystem tools.
The logical maximum VHD size, governed by the disk configuration and the filesystem’s capacity.
Bytes currently allocated to the VHDX file on the Windows volume.

A dynamically growing VHDX can allocate fewer host bytes than its guest filesystem’s logical capacity. Conversely, deleting Linux files can create free blocks inside ext4 without immediately reducing the VHDX file’s host allocation. The first condition is ordinary dynamic growth; the second is why WSL documents separate compaction steps. A Windows file-size report is not a replacement for df, and Linux free-space output is not a prediction of exact host allocation.

Current Microsoft documentation lists defaultVhdSize under [wsl2], with a default value of 1 TB, and describes it as the size of the VHD storing the Linux distribution filesystem. It says the value can limit the maximum size the filesystem is allowed to take up. The current disk-space guide separately explains default VHD limits and how to expand a VHD. Earlier WSL releases used different maximum defaults, so record wsl --version instead of assuming the current table describes an older inbox runtime.

Set an intentional ceiling in `.wslconfig`

The file is global to WSL 2 distributions for the Windows account. A simple example is:

# %UserProfile%\\.wslconfig
[wsl2]
defaultVhdSize=256GB

Size values accept documented units such as GB or TB; plain numeric values are bytes. Use a human-readable unit and review the exact value before applying. Keep this entry in the existing [wsl2] section, and preserve unrelated memory, networking, and kernel settings. WSL Settings can edit supported global configuration, but the resulting file and effective disk behavior still need validation.

The ceiling should match a workload and host-volume budget, not a guess copied from another machine. A large monorepo, local container images, package caches, and test databases may consume more than a small shell environment. At the same time, choosing an enormous maximum does not reserve that amount of host storage in a dynamic disk, but it does permit the guest filesystem to grow much larger before the guest encounters its own disk-full boundary. Monitor free bytes on the Windows volume separately from Linux capacity.

Microsoft’s current WSL triage guidance recommends defaultVhdSize when importing a new distribution that needs a different maximum; for an existing distribution that must grow, it directs users to the supported VHD expansion instructions. Do not promise that editing the key will shrink or retroactively change an already-created filesystem. For an existing distro, inspect the actual capacity and follow the operation documented for that state.

Apply the global configuration safely

Record the WSL version, Windows build, existing .wslconfig, distro name, and current filesystem capacity before editing. Configuration changes are applied when WSL restarts. Close workloads cleanly and use a full shutdown only when appropriate:

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

wsl --shutdown stops all running distributions and shared WSL 2 VM processes. It can interrupt containers or databases, so quiesce those services before using it. Changing defaultVhdSize does not itself guarantee that every distro’s filesystem is changed at once; verify the distribution’s effective capacity after its own documented creation or resize operation.

When importing a new distribution, use the supported import workflow and set the global ceiling beforehand if the current WSL runtime uses that value for the import. Keep the rootfs archive and any data backup separate from the destination VHD. A successful import only shows registration and filesystem extraction completed; it does not prove that the resulting filesystem has the capacity your workload requires. Inside Linux, inspect df -hT / and create a bounded test file only if a safe acceptance test requires exercising actual writes.

Expand an existing VHD with the supported management path

For a current WSL release that supports wsl --manage, Microsoft’s disk-space documentation describes expanding an existing distribution VHD with wsl --manage <distribution> --resize <size>. The operation may require the WSL 2 instances to be shut down first and can include filesystem checks and resize operations. Read the current documentation for exact release requirements and permitted target sizes before running it; do not copy a command from a different WSL version blindly.

wsl.exe --shutdown
wsl.exe --manage Ubuntu --resize 300GB

This is an example of an expansion operation, not an instruction to shrink an existing disk or a backup procedure. Verify that the target distro name exactly matches wsl --list --verbose, that the Windows volume has adequate headroom, and that a verified backup exists before changing important data. After the command reports success, start the distro and check the Linux filesystem capacity again. If the guest still shows the old capacity, stop and diagnose the filesystem/device layer instead of repeating the operation with random values.

If the installed WSL package predates the management option, consult Microsoft’s current manual expansion procedure and verify all preconditions. Never run a host-side filesystem repair tool directly against a VHD that is mounted or in use by WSL. Do not move, mount, or edit opaque WSL-managed files from Windows while the distribution is running.

Triage a full disk without confusing capacity and allocation

Inside the distro, gather:

df -hT /
df -i /
du -xhd1 / 2>/dev/null | sort -h

df -i helps distinguish inode exhaustion from byte exhaustion. du can identify large directories but may not account for every allocated filesystem structure or deleted-but-open file. Use it as a clue, then inspect containers, build caches, logs, snapshots, and application data with their own tools. If a file was deleted while a process still holds it open, freeing directory entries may not free storage until that process closes the descriptor.

From Windows, inspect the host volume’s free space and the VHDX’s current file allocation only through safe, read-only views. Compare the guest’s used/free values with the Windows file allocation and host-volume capacity. A gap is expected for a dynamically allocated disk; a small host-volume free-space margin is still an operational risk even when df shows guest free space. Avoid hard-coding a path under AppData because imported and packaged distributions can store their VHDs in different locations.

If the guest is full, remove or archive data inside Linux first, then re-evaluate df. If the guest needs more logical capacity, expand the existing VHD using the documented workflow. If the Windows host volume is nearly full, migrate storage using supported WSL management or export/import procedures rather than manually moving a live VHDX. If space was freed but host allocation did not shrink, consult the separate sparse/compaction guidance; a lower defaultVhdSize value is not a compaction command.

Acceptance criteria and change record

A capacity change is complete when the documented WSL runtime version is confirmed; the configuration is in the right Windows user profile and section; all affected workloads start after the planned restart; the distro reports the expected filesystem capacity; a small, reversible write test succeeds if appropriate; and the Windows volume retains a monitored safety margin. Record guest capacity and VHDX allocated bytes as different metrics.

Keep the old .wslconfig, export or backup important distro data, record the target size and why it was selected, and define who monitors host free space. A global setting can affect future WSL 2 operations beyond the one distro that exposed the problem. A measured ceiling, a supported resize path, and separate host/guest monitoring are safer than treating a single “disk size” number as the whole storage story.

Related:

Sources: