WSL Hostname Identity: Set a Stable Linux Name Per Distribution

A WSL distribution has a Linux hostname even though it runs on a Windows host. Microsoft’s current configuration reference says WSL uses the Windows hostname by default. The per-distribution hostname key in /etc/wsl.conf lets an operator select a different name. That helps with shell prompts, logs, local scripts, and software that reads Linux machine identity. It does not rename the Windows computer, create a DNS record, or guarantee that another device can resolve the chosen value.

Hostname is often mistaken for a network shortcut. It is an identity input exposed inside Linux. Name resolution, Windows device naming, network reachability, and service discovery are separate systems. A good configuration gives each distribution an intentional, recognizable Linux name while leaving DNS and firewall policy to their own owners.

Start with the configuration contract

Microsoft documents [network] hostname in wsl.conf, with the Windows hostname as its default. wsl.conf is stored under /etc, affects only the distribution that contains it, and can be used by WSL 1 or WSL 2 when the Windows build supports per-distribution settings. This differs from .wslconfig, which controls global WSL 2 settings.

For example, a distribution registered as Ubuntu-Dev could use:

[network]
hostname=ubuntu-dev

Treat this as a per-distro configuration value. If Debian and Ubuntu should have different labels, place the appropriate setting in each distro’s own /etc/wsl.conf; editing one file does not configure its sibling. Keep the section and other existing keys intact. Do not replace the whole file with a snippet if it already controls generateHosts, generateResolvConf, automount, systemd, or interop.

Hostname configuration support begins with the Windows build documented for wsl.conf; feature availability also depends on the installed WSL servicing channel. Capture wsl.exe –version, wsl.exe –status, and the Windows build before relying on the setting in a managed fleet. A key appearing in current online documentation does not prove that every older inbox runtime recognizes it.

Choose a name for Linux identity, not for DNS

The Linux hostname command reports the system’s configured host name. hostnamectl status provides systemd-oriented information where systemd is present; minimal distributions or WSL 1 environments may not provide the same command or fields. uname -n is a useful independent check of the kernel-reported node name. These commands answer what Linux currently sees, not whether a DNS server has an address record for that name.

Use a short, stable label meaningful to the human operating the distribution: ubuntu-dev, debian-ci, or fedora-lab are better than a temporary project codename that changes every week. If a hostname will be used as a DNS label or embedded in URLs, choose a conservative DNS-compatible form: lowercase letters, digits, and hyphens, with no leading or trailing hyphen. Linux tools may accept strings that a DNS naming policy rejects, so “the kernel accepts it” is not the same as “every resolver, certificate, or monitoring system accepts it.”

Do not assign the same label to multiple simultaneously used environments if operators rely on it to identify a source in logs. WSL distributions on one Windows account may share a Windows host name by default. A per-distro name can make local output easier to distinguish, but it is not a globally unique identifier. A CI worker, restored backup, or cloned Windows profile can use the same value. Include the distro name and a stable machine or job identifier in telemetry when uniqueness matters.

Keep the hostname separate from local host mappings

/etc/hosts is a local static mapping between names and addresses. The WSL [network] section independently controls whether WSL generates that file through generateHosts; the default is true. Changing hostname does not document or promise a corresponding custom address record in /etc/hosts. Inspect the generated file after a restart rather than assuming the chosen name maps to 127.0.0.1, a WSL virtual address, or a Windows address.

Similarly, generateResolvConf governs /etc/resolv.conf, not the hostname. DNS tunneling, mirrored networking, NAT, VPN policy, suffix search lists, and external authoritative DNS are separate concerns. A command such as getent hosts ubuntu-dev tests the resolver path currently configured in Linux; it does not prove that Windows DNS or a corporate DNS server contains that name.

If an application needs a local alias, manage it explicitly through the appropriate Linux resolver mechanism, a controlled hosts-file entry, or a real DNS record. Avoid editing a WSL-generated file and expecting the change to survive boot. If generation is intentionally disabled, document who owns that file and how the resolver configuration is reproduced. A hostname change should not be used as a substitute for a DNS record, a TLS certificate name, or a routable service endpoint.

Understand the interaction with Linux tools

Linux applications commonly read the hostname for prompts, syslog fields, metrics labels, package scripts, or application diagnostics. Some services cache identity at process start, so a changed hostname may require a service restart even after Linux reports the new value. A daemon’s configuration can also hard-code a different name. Validate the exact property consumed by the workload rather than using the shell prompt as the sole acceptance test.

Systemd can persist a static hostname in distribution files on a conventional Linux installation. WSL adds a host-managed startup layer, so an operator should avoid running hostnamectl set-hostname and writing [network] hostname as two competing sources of truth. Decide whether WSL configuration owns the value. If it does, edit wsl.conf, restart the distribution fully, and treat a one-off runtime change as diagnostic rather than durable configuration.

This also matters for software that derives a machine identity once and persists it. Changing the hostname is not a reliable way to rotate an SSH host key, regenerate an application identity, or make a database replica safe to clone. Those objects have their own lifecycle. If a service uses hostname as a cluster node ID, check its own documentation for renaming procedures before changing WSL configuration; the WSL setting cannot rewrite application metadata or remote membership state.

Apply the change with a controlled restart

wsl.conf is read during distribution startup. Close processes that must stop cleanly, save work, and terminate only the target distro where possible:

wsl.exe --terminate Ubuntu-Dev
wsl.exe --distribution Ubuntu-Dev --exec /bin/true

If a setting appears unchanged because the instance did not stop, verify with wsl.exe –list –running. wsl.exe –shutdown stops every running WSL 2 distribution and its utility VM, so reserve it for cases where a full VM restart is necessary and coordinate other active distros first. Microsoft’s configuration guide describes waiting for the subsystem to stop before expecting edits to take effect.

After relaunch, capture both the host-side distro registration name and guest-side hostname:

wsl.exe --list --verbose
wsl.exe --distribution Ubuntu-Dev --exec hostname
wsl.exe --distribution Ubuntu-Dev --exec uname -n

From inside Linux, inspect cat /etc/wsl.conf, hostname, uname -n, and relevant /etc/hosts content. If hostnamectl exists, compare its reported static and transient names, but do not assume it is installed or that its output defines WSL’s configuration precedence. Then restart any service whose logs or metrics should contain the updated identity and inspect a new event generated after that restart.

Use measurable acceptance criteria

Before the change, record the current value from hostname and uname -n, the WSL package version, Windows hostname, distro registration name, and whether WSL generates hosts and resolver files. Afterward, require the intended Linux node name to appear after a fresh distro start, remain stable across a second terminate-and-launch cycle, and be visible in a test log emitted by the target service. If the name is expected to resolve, separately test getent hosts <name> inside Linux and the relevant Windows or network resolver from its own client.

Do not claim success because the shell prompt changed. Prompts are often configured by shell startup files and can display an arbitrary string. A successful hostname query verifies kernel-facing identity; a successful resolver query verifies one naming path; a service log verifies the application consumed the intended value. These are distinct checks.

Rollout and rollback

For a fleet of developer images, treat hostname as a small but observable per-distro setting. Add it to distribution provisioning source, not a one-time manual command. On image upgrades, compare the value in /etc/wsl.conf with the name reported by Linux. If a distro is imported or restored under a new WSL registration name, do not assume its hostname changes automatically; the two names identify different layers and may intentionally differ.

Rollback consists of restoring the prior hostname key or removing the override to return to the documented Windows-hostname default, then restarting the distro. Preserve unrelated [network] settings. If a remote system has already registered the old hostname, coordinate the application or DNS owner before changing it back; WSL can change only the local configured name, not repair external inventory.

The practical rule is simple: set the Linux hostname when Linux processes need a clear, per-distribution node label. Use explicit DNS, /etc/hosts, certificate, and service-discovery mechanisms for reachability. Keeping those responsibilities separate makes WSL logs more readable without creating a false promise that a label is resolvable or network-unique.

Related:

Sources: