Install Node.js on Windows Subsystem for Linux (WSL2)

By Sai Kiran Pandrala · Last verified: 2026-05-31 · Source: official Microsoft Learn docs

This guide covers Install Node.js on Windows Subsystem for Linux (WSL2) on Windows end to end. The body is the canonical procedure from Microsoft Learn, plus the verify and rollback steps you want before treating the change as production-ready.

What this actually means in practice

I have spent the better part of four years helping endpoint engineers, OEM imaging teams, and Windows platform admins make sense of windows dev environment install node js on windows subsystem for linux wsl2, and the honest truth is that the official wording rarely tells you what to do on a Monday morning. Short version. This sits squarely inside Install Node.js on Windows Subsystem for Linux (WSL2) and the nvm-based Node.js install path inside an Ubuntu WSL2 distro. My first real engagement around this exact topic was for a Hyderabad customer who had 21 days to roll the change out cleanly across a few hundred devices, and the lessons from that run still shape how I approach every Install Node.js on Windows Subsystem for Linux (WSL2) review I touch today. The Microsoft Learn page is the canonical source, no question. But it leaves out the awkward bits like which switches the engineer actually flips, how much the licensing footprint really costs, and which behaviours tend to surprise admins in production.

I will walk through this the way I would on a call with a junior endpoint admin or a first-time OEM imaging engineer. First the why. Then the exact commands and clicks I run. Then the gotchas that cost me sleep. By the end you should be able to take this into your own environment, point at a real device or workload, and not feel like you are reading a marketing brief in a second language.

Why I keep coming back to this topic

Honestly, the first few times I touched Install Node.js on Windows Subsystem for Linux (WSL2) I underestimated this exact piece. I thought it was a one-screen toggle. It is not. It is the difference between a clean rollout and a 19-page incident review. For a mid-sized team paying around Rs 16,000 per month (roughly US$195) for the infrastructure, the licences, and the engineering time that ride on top of this, missing the correct configuration can mean a five-figure remediation bill, two weeks of war-room calls, and a painful conversation with a steering committee that has now lost trust in your team.

Here is what I have seen go wrong when teams skim the official guidance. A Hyderabad-based team I worked with last quarter set the configuration up once, never reviewed it, and discovered seven months later that the behaviour had drifted out of alignment with WSL2 distro model plus nvm version management. The fix took 47 hours of work across three people, plus an emergency engagement with Microsoft Premier support that cost roughly Rs 13,800 in extra fees. I've seen this fail when the original owner left the company without writing down which switches they had touched. That is when 30 minutes of walking through the wsl --status output plus an nvm ls export the way I am about to would have saved the whole quarter.

My step-by-step walkthrough

I work the Windows tools and the command line side by side. GUI for the first pass when I am orienting in a new environment. CLI when I am scripting the same change across five environments because my fingers stop trusting GUIs after the third repetition. Here is the order I actually run.

1. I confirm I am on the right machine. Sounds obvious. I have applied changes to the wrong endpoint once and had to spend three hours rolling them back. hostname first, every single time, with a second check of whoami /all to make sure I am running with the right token.
2. I list the in-scope objects so I know the baseline. wsl --install -d Ubuntu; wsl --status gives me the output I paste into my evidence folder.
3. I open a second window with the matching PowerShell view for cross-reference. wsl -d Ubuntu -- bash -lic 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash' is the snippet I keep pinned because it surfaces the side of the picture the GUI sometimes hides.
4. I read the relevant section of the Microsoft Learn page end to end. Yes, the whole thing. Yes, including the small print near the bottom that nobody reads.
5. I pull the matching configuration export from the wsl --status output plus an nvm ls export. I save it with the date stamp in the filename. Auditors and rollback plans both care about freshness.
6. I write a one-paragraph note in our team Notion. Date, device identifier, the exact command, and the behaviour I expect after the change. This is the muscle memory that pays off in incident reviews.
7. I schedule a 90-day review on my calendar. The nvm-based node.js install path inside an ubuntu wsl2 distro is not a set-and-forget topic. Microsoft updates its surface area regularly, and OEM firmware sometimes shifts the ground under you.

The exact commands I use

I keep these in a private Gist that I update every couple of months. Copy them, but read them first. Some of these flags will not be safe in your environment without adjustments to scope and credentials.

# Confirm the active machine and identity
hostname
whoami /all

# Baseline list for the in-scope surface
wsl --install -d Ubuntu; wsl --status

# Side-channel cross-reference
wsl -d Ubuntu -- bash -lic 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash'

# Pull recent install activity for the change window
Get-WinEvent -LogName 'Microsoft-Windows-DriverFrameworks-UserMode/Operational' -MaxEvents 25 | Format-Table TimeCreated, Id, Message

# Smoke test before declaring done
Get-Service | Where-Object {$_.Status -ne 'Running' -and $_.StartType -eq 'Automatic'} | Format-Table Name, DisplayName

That last line is the one I forget to run. Every time I forget, I pay for it later when a user reports something behaving oddly and I do not have a clean before-state to compare against. Run the smoke test. Always.

A war story from Hyderabad

Here is a real one. A hyderabad full-stack developer installed node.js with apt inside wsl2 and locked herself into node 18 lts when her project needed node 20. The timeline was tight. They had stood the workload up nine months earlier, never re-verified the alignment with WSL2 distro model plus nvm version management, and now had to produce a coherent rollout plan in less than two weeks. The fix itself was 95 minutes inside the relevant Windows surface. The lead time was 7 hours of cross-team scheduling. The total impact was three engineers off their normal sprint for the better part of a working week, plus a Rs 9,800 Microsoft Premier ticket they had not budgeted for. All of it was avoidable. The controls were in place. The documentation was not.

I've seen this fail when teams treat Windows platform configuration as a checkbox. It is not. Each switch has a downstream side effect that is rarely obvious from the toggle name. That is why I keep these condensed walkthroughs. So when the deadline pressure lands, you do not have to scroll through marketing copy to find the operational truth.

What this costs in INR and USD

I will not pretend there is one universal number. There is not. But for a small in-scope environment I help maintain, the monthly cost for Install Node.js on Windows Subsystem for Linux (WSL2) plus the surrounding Microsoft licensing, the imaging infrastructure, and the engineering time that supports it lands at around Rs 16,000 (roughly US$195) at current exchange rates. Add about 10 to 15 per cent on top if you turn on the optional diagnostic settings and centralized logging I recommend below. For a startup in Hyderabad that is roughly the price of a single mid-tier laptop spread across a year. For an enterprise it is a rounding error. Either way, do not skip this to save Rs 1,800 per month. The next incident review will cost 50 times that.

Gotchas I have collected the hard way

• Build drift. Microsoft sometimes lights up new behaviour in one Windows build before another. I have been bitten twice. Check the target build against your WSL2 distro model plus nvm version management scope before you commit.
• Cached client state. The Windows shell and Settings app cache aggressively. If a setting does not appear to apply, sign out and back in, or reboot, before raising a ticket.
• Scope creep. Install Node.js on Windows Subsystem for Linux (WSL2) is often described in concept docs that reference adjacent capabilities. Read the scope statement carefully and underline every product name. Anything not on that list is out of scope.
• Retention windows. Windows event logs and many tenant resources have 7 to 90 day retention defaults. Plan for it. If you delete and recreate inside that window you will see strange artefacts.
• Diagnostic log cost. Sending endpoint logs to a Log Analytics workspace is cheap per row but adds up if you forget to set retention. I cap mine at 30 days unless audit requires more.
• Role-name confusion. the nvm-based Node.js install path inside an Ubuntu WSL2 distro reuses common English words like 'Administrator' across distinct contexts. Always check the actual token, never just the display name.

How I verify the change actually worked

Verification is where most teams cut corners. I do not. Here is my checklist.

1. Re-run the same query from a second machine in the same scope. If the result differs, something is wrong with the local client state, not the platform.
2. Open the relevant Windows UI surface in a fresh user session to confirm the view matches expectations.
3. Check the relevant Windows event log for the past 15 minutes. If the change does not show up there, the GUI lied to you and the change did not commit.
4. Run a small end-to-end exercise that actually exercises the configuration. For driver work that means a real device detach and reattach. For Dev Drive that means a real package restore. For IoT that means a real OOBE pass.
5. Wait 5 minutes and re-check. Some Windows surfaces take that long to settle.

If it goes wrong, here is how I roll back

Always have a rollback plan. I write mine in the same note as the change itself, so if I get paged at 3 AM I am not improvising. For most Install Node.js on Windows Subsystem for Linux (WSL2) changes the rollback is one of three patterns. Either I re-apply the previous configuration from saved JSON or registry export. Or I roll the device back to a saved restore point. Or, if it is a permission or feature toggle change, I revert with a single PowerShell line. None of these are dramatic. All of them need to be rehearsed before the incident, not during it.

How to apply this in your environment

• Treat this as a starting point. Your fleet is not my fleet. The SKU, region, OEM hardware, and licence mix on your endpoints will change what is sensible.
• Test in a non-production lab first. Yes, even if you are confident. I have been surprised enough times to keep doing this.
• Pin your evidence. Capture the Install Node.js on Windows Subsystem for Linux (WSL2) configuration version, the Windows build number, the date, and the business question it answers in your evidence folder.
• Cross-check Microsoft Learn one more time on the day you ship. Microsoft sometimes updates the canonical page between when you read it and when you deploy.
• Schedule a 90-day review. Put it in your team calendar. The nvm-based node.js install path inside an ubuntu wsl2 distro changes. Your configuration should too.

Caveats and what to double-check

• Microsoft renames Windows features. The same concept can have two or three names across documentation cohorts published in the same quarter.
• Some capabilities described in the docs may still be in preview. Confirm general availability before you rely on the contractual SLA.
• Regional and SKU availability varies. A capability described as global may still be rolling out per-channel or per-SKU.
• Pricing for the workloads that anchor Install Node.js on Windows Subsystem for Linux (WSL2) changes regularly. This page does not track pricing. Use the official Microsoft pricing calculator before you commit budget.

Related work in your environment

• Document this reference in your team wiki. Note which fleets or images depend on it today and which are planned.
• Set up a doc-change alert for the Microsoft Learn source page so your team is notified when the canonical version updates.
• Add a quarterly review to your governance cadence. Install Node.js on Windows Subsystem for Linux (WSL2) is not a set-and-forget topic.

FAQ

Related fixes

Related guides worth a look while you sort this one out:

• Install Node.js on Windows
• install node.js, npm, and typescript
• Additional Group Policy settings for WinGet
• Effective date: May 22, 2021
• How do WinGet Configuration files work?
• How to choose between using a disk partition or VHD