WSL Idle Timeout Policy: Distinguish Distro and VM Shutdown Windows

WSL publishes two idle-shutdown settings with similar names but different scopes: instanceIdleTimeout in the global [general] section and vmIdleTimeout in [wsl2]. Microsoft’s current configuration reference gives defaults of 15,000 and 60,000 milliseconds respectively. The first describes how long a distribution is idle before it is shut down; the second describes how long the WSL 2 virtual machine is idle before it is shut down. These are not documented as a single additive timer. Do not assume that a service remains available for exactly 75 seconds after its last request.

This article is about measuring and configuring those host-managed lifecycle windows. It is separate from systemd unit behavior: systemd can supervise processes inside a running distro, but it does not own the WSL host’s idle policy. A timeout change also cannot turn an interactive developer workstation into an availability-managed Linux server.

Identify the two controls and their scope

instanceIdleTimeout belongs under [general] and applies as a global WSL configuration setting. Its documented unit is milliseconds, its default is 15,000, and the reference lists -1 as the value that disables automatic shutdown. vmIdleTimeout belongs under [wsl2], is documented with a 60,000 millisecond default, and describes the idle duration before the VM shuts down. The latter is specifically a WSL 2 virtual-machine control; WSL 1 does not run inside that same utility VM.

For example, a test configuration could be:

[general]
instanceIdleTimeout=60000

[wsl2]
vmIdleTimeout=120000

These values are examples for a controlled experiment, not recommendations. Preserve existing settings, merge into current section headers, and avoid duplicate sections. Do not copy -1 to vmIdleTimeout unless current Microsoft documentation explicitly says that sentinel is supported for that key; the documented -1 behavior is associated with instanceIdleTimeout.

.wslconfig lives in the Windows user profile and is shared across WSL 2 distributions for that user. It is not a per-distro file and cannot express a different idle policy for each Ubuntu, Debian, or imported distro. /etc/wsl.conf has a per-distribution scope, but these two settings are not documented there.

Why the two timers should not be conflated

The configuration reference defines the unit and object affected, but does not fully specify every internal activity that counts as “idle,” exact timer reset events, or how the two thresholds are scheduled relative to one another. It also does not promise that the values are added into an externally predictable shutdown instant. Background processes, other distributions, WSL integrations, and workload activity can affect the observed lifecycle.

Do not infer a specific timer model from a single trial. A closed terminal is not necessarily the same as an idle distribution, because a background service, editor integration, container engine, or another process can keep a distro active. A stopped distro is not the same as a stopped VM if another WSL 2 distro still uses that shared VM. The documented scopes tell you what to measure; they are not a substitute for observing the installed WSL release.

Also distinguish these host controls from wsl.exe –terminate and wsl.exe –shutdown. Terminate is an explicit request to stop one named distribution. Shutdown explicitly terminates all running distributions and the WSL 2 utility VM. Those commands are operator actions, not idle-timeout settings. They can stop stateful applications immediately, so use workload-aware shutdown procedures before invoking them.

Build a baseline before tuning

Record the WSL package version, Windows build, distribution names and versions, current .wslconfig, and whether the workload is WSL 1 or 2. These read-only commands provide a starting point:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose
Get-Content "$env:USERPROFILE\.wslconfig" -ErrorAction SilentlyContinue

In each distribution, record expected long-running processes, service state, open database files, container sessions, and any external health check. Use a benign test service rather than a production database for the first experiment. Capture a timestamp immediately before the last client disconnects and poll wsl.exe –list –running from Windows at a fixed interval. That command reports distro running state; it does not necessarily expose every VM-internal timer transition.

To identify observed idle conditions, test separate cases: no Linux process after a one-shot command; one known long-lived process; a service under systemd; and two running distributions where one is idle and one remains active. Do not run all cases concurrently because their activity can contaminate the VM-level observation. Keep Windows power state, VPN connection, WSL version, and host load constant.

The goal is not to reverse-engineer undocumented internals by guesswork. Instead, record whether a distro or VM stops under a repeatable workload, how long it takes, and whether the relevant application is still expected to be available. If the observed result differs from the documented timeout, preserve logs and environment details and verify the installed WSL version before changing values.

Change one timeout at a time

Start from the default configuration and adjust only the setting tied to the observed requirement. If a development tool loses local state because a distribution is reclaimed too soon, test a larger instanceIdleTimeout. If the goal is to control how long a completely unused shared VM remains, test vmIdleTimeout as a separate variable. Avoid changing both at once; otherwise a passing test does not identify which setting mattered.

Apply .wslconfig edits with a complete, controlled VM restart. Microsoft notes that global settings may require wsl.exe –shutdown; it stops every running WSL 2 distribution. Before using it, list running distributions, stop databases and other stateful workloads cleanly, and ensure no build, sync, or backup task is in flight. Restart one test distro, then verify the active configuration and collect results.

Use a table with intended and observed state:

Trial	WSL version	Setting changed	Other active distros	Observed stop time	Workload result
Baseline	Recorded package	Defaults	None	Measured	Pass/fail
Change A	Same package	One key only	None	Measured	Pass/fail
Concurrent distro	Same package	Same config	One active	Measured	Pass/fail

Run at least five trials per condition when behavior is timing-sensitive. Report median and range, not one fastest run. Do not claim millisecond precision; your polling interval, process scheduling, and VM startup overhead limit measurement precision.

Design services around WSL’s lifecycle

If a service must stay available after a terminal closes, first decide whether the requirement is “during a working session,” “until the distro becomes idle,” or “always available independent of user activity.” These are different service contracts. A systemd unit can be enabled and healthy while its containing distribution runs, yet the WSL host may later stop the environment. The two timeout settings affect that outer layer, not the unit’s restart policy or readiness state.

For an interactive development service, a longer idle window may improve convenience. For scheduled work, use an external Windows scheduler or service manager to start WSL at the required time, while still accounting for Windows login, power, policy, and update behavior. For a production availability requirement, use a server or cloud environment designed for continuous service; do not disable idle shutdown and assume that alone provides uptime.

Stateful software needs an independent durability plan. A timeout can stop a process while it has buffered state; application-level graceful handling, transactional storage, backups, and restore testing remain necessary. Before changing a timeout on a database or container host, define a clean-stop hook and validate recovery from an intentional termination in a disposable copy.

Acceptance criteria and rollback

Write acceptance criteria before editing. Examples include: a dev server remains available for at least the team’s observed break interval; an idle distro stops within the chosen resource-reclamation budget; a second active distro is not unintentionally terminated by a test; and an application is healthy after a controlled restart. Use an application health endpoint or representative command rather than interpreting wsl.exe –list –running as proof the service works.

Rollback by restoring the exact prior values, removing only the changed keys, and restarting WSL 2. If instanceIdleTimeout=-1 is used, treat it as disabling automatic shutdown only for that documented setting; it does not prevent Windows shutdown, manual WSL commands, package servicing, or policy from stopping WSL. Do not imply that a timeout setting pins memory or reserves CPU.

After a WSL package update, repeat the small acceptance test. Defaults and feature behavior are documented by a moving WSL configuration page; the exact runtime on a workstation can lag the current reference. Store results with the WSL version and Windows build, and revisit the setting when the team’s expected idle behavior changes.

The operational rule is to set the smallest timeout that satisfies a measured workload need, keep distro-level and VM-level scopes distinct, and report unverified timing behavior honestly. These controls help tune workstation lifecycle. They are not a substitute for application-level shutdown safety or service availability engineering.

Related:

Sources: