WSL 2 Kernel Command-Line Parameters: Configure, Verify, and Roll Back

WSL 2 lets an administrator pass additional arguments to its Linux kernel through the global %UserProfile%\\.wslconfig file. This is a narrow compatibility and diagnostics control, not a substitute for changing distribution settings, rebuilding a kernel, or applying a Linux bootloader configuration. Because .wslconfig is shared by WSL 2 distributions on the Windows account, one experimental kernel argument can affect every WSL 2 workload that starts afterward. The safe workflow is to identify a documented parameter for a real requirement, verify that the running kernel received it, measure the intended behavior, and remove it promptly if the result is uncertain.

Understand which layer owns the setting

kernelCommandLine belongs under the [wsl2] section of the Windows-side .wslconfig. It is not an /etc/wsl.conf key and is not a per-distribution bootloader setting. WSL 1 distributions do not use the WSL 2 Linux virtual machine and are outside this setting’s scope. A global kernel argument therefore needs a broader change review than a package or service configuration inside one distro.

The setting adds arguments to the kernel command line. It does not let a distro provide its own kernel, compile an option that was not built into the kernel, or change a setting in a running kernel after startup. Those are separate mechanisms. If the required kernel feature is absent, consult Microsoft’s WSL kernel source and supported custom-kernel workflow rather than trying to compensate with a command-line parameter that the kernel does not recognize.

Linux kernel parameters are version- and configuration-dependent. The upstream kernel parameter index describes recognized names and semantics, but the WSL kernel can differ from a generic kernel in version, configuration, or Microsoft-specific patches. Before using a parameter, identify the WSL kernel with uname -a, find the exact parameter in documentation for the relevant kernel, and confirm that the WSL kernel supports it. Do not copy an argument from a boot guide for a different distribution or hypervisor without checking its meaning and availability.

Record a baseline before editing

From PowerShell, capture the Windows and WSL component versions, registered distributions, and current configuration. From each relevant WSL 2 distribution, record the kernel release and the value of /proc/cmdline:

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

uname -a
cat /proc/cmdline

Keep the output free of unrelated secrets and note the exact distro name used for each guest-side check. /proc/cmdline is runtime evidence that the kernel received a command line; it does not prove every option was recognized or that a requested feature is active. For a parameter with an observable effect, capture a second, independent signal such as a documented sysctl value, kernel log message, or workload behavior.

If there is no reproducible problem or testable requirement, leave the default alone. Kernel parameters can change logging volume, memory behavior, device initialization, security mitigations, or compatibility. A harmless-looking parameter on one workload may have a different cost when applied to another distro sharing the VM.

Make a small, reviewable change

Suppose a kernel-level diagnostic needs more visible console messages. The upstream kernel documents loglevel= as a way to set the console log level. An illustrative configuration is:

# %UserProfile%\\.wslconfig
[wsl2]
kernelCommandLine = loglevel=7

This example is for a bounded diagnostic test, not a recommendation to leave verbose logging enabled. The kernelCommandLine value is a string of kernel arguments separated by spaces. Keep one key in the existing [wsl2] section, preserve memory, networking, kernel, and other settings already present, and do not create competing duplicate entries. If a parameter requires quoting or has a complex value, validate the exact syntax against current WSL configuration documentation and the upstream kernel parameter documentation before applying it.

Do not place shell syntax such as sudo, environment variable assignments, or semicolon-separated commands in this field. WSL passes kernel arguments before Linux userspace exists; it does not execute a shell command there. Likewise, a kernel argument is not an environment variable and cannot configure a particular user’s interactive shell.

Restart deliberately and verify effective state

Changes to .wslconfig take effect when the WSL 2 VM starts with the new configuration. Closing a single terminal is not enough if another distro, editor, container tool, or background process is keeping WSL active. A deliberate restart is:

wsl.exe --list --running
# Stop stateful Linux services cleanly before a shared-VM shutdown.
wsl.exe --shutdown
wsl.exe --distribution Ubuntu --exec uname -a

wsl --shutdown stops all running WSL distributions, so it can interrupt unrelated services. Arrange a maintenance window if that matters, and stop databases or other stateful processes using their normal guest-side procedure first. Restart one test distro and inspect /proc/cmdline; then test a second representative distro because the kernel setting is global.

The acceptance test should be defined before changing the value. For a diagnostic verbosity test, verify the command-line argument is present and compare the expected messages for a reproducible boot or device event. For a compatibility workaround, run the application or system call that motivated the change and also test ordinary filesystem, networking, and service startup. Do not declare success because the file parses or uname prints a version string.

Diagnose a value that appears to be ignored

First confirm that the file is named exactly .wslconfig, is in the active Windows user’s profile, and contains the key beneath [wsl2]. Then ensure the test distro is WSL 2, record wsl --version, perform a full WSL shutdown, and inspect /proc/cmdline after restarting. Configuration keys have evolved with Store-delivered WSL, so an old inbox runtime may not support every current key. A stale or malformed file can also be ignored while WSL continues to start.

If the argument is visible in /proc/cmdline but behavior does not change, investigate the parameter itself. It may be unsupported by that kernel build, may apply only under a different boot or device path, or may require a kernel compile-time option. Search the exact kernel version’s documentation and inspect dmesg for a clear warning only when the symptom and logging path justify it. Do not stack several experimental arguments in the hope that one fixes the issue; doing so destroys the ability to attribute cause.

An argument that produces a boot failure can usually be rolled back from Windows because .wslconfig is outside the Linux filesystem. Remove only the kernelCommandLine entry or comment out the experimental argument, then run wsl --shutdown and start one distro again. Keep a copy of the previous file and do not delete or unregister a distribution as a configuration recovery step.

Keep a kernel-parameter change auditable

For a managed workstation, store the reason, exact argument, supporting kernel documentation, WSL version, Windows build, affected distributions, and rollback condition with the configuration change. Revalidate it after WSL kernel updates: a parameter can be renamed, deprecated, or acquire different semantics in a later kernel. A parameter that exists in upstream Linux documentation is not automatically guaranteed to be supported by every Microsoft WSL kernel build.

For incident response, distinguish the requested state from the effective state. The .wslconfig file expresses intent; /proc/cmdline shows the command line seen by a running kernel; and a test of the relevant feature demonstrates behavior. Capture all three before closing the change. If only the configuration text is known, report the result as unverified rather than claiming the kernel applied it.

The smallest robust change is one parameter, one controlled restart, a before-and-after measurement, and a simple rollback. That discipline matters more in WSL than the short file suggests: its global scope can affect Linux development environments, local clusters, containers, and long-running services at the same time.

For a kernel logging experiment, compare the same event under the same boot conditions rather than counting all emitted lines. A higher console log level can make early initialization easier to inspect, but it can also produce more output and may not increase the amount retained in every downstream logging path. If the event is generated after userspace starts, a system journal or application log may be a better evidence source. Kernel parameters should be selected according to the stage they can affect, not because they sound broadly diagnostic.

When validating a custom-kernel parameter, record both the WSL kernel release and the configuration or commit from which that kernel was built. Two kernels reporting similar version strings can differ in enabled options. If a command-line argument appears in /proc/cmdline but the kernel’s documented response is absent, check kernel configuration and parameter scope before claiming WSL ignored the configuration. A reproducible minimal test makes the issue report useful to a kernel maintainer and limits the chance of treating an unrelated userspace setting as a boot-argument defect.

Related:

Sources: