[{"data":1,"prerenderedAt":496},["ShallowReactive",2],{"en-post-46":3},{"id":4,"title":5,"body":6,"description":12,"extension":489,"meta":490,"navigation":491,"path":492,"seo":493,"stem":494,"__hash__":495},"content/post/46.md","46",{"type":7,"value":8,"toc":473},"minimark",[9,13,18,21,24,37,40,44,47,53,70,73,89,100,104,109,124,144,147,151,156,167,171,194,207,211,222,251,258,262,269,273,279,283,363,372,376,410,414,425,429,469],[10,11,12],"p",{},"Want a Linux development environment without dual-booting or a heavy virtual machine? WSL2 (Windows Subsystem for Linux 2) runs a full Ubuntu or other distro right inside Windows, starts in about a second, and lets you reach Windows files, run Docker, and use VS Code remote development. This guide covers install, configuration, and daily use from scratch.",[14,15,17],"h2",{"id":16},"what-wsl-is-and-why-wsl2","What WSL is and why WSL2",[10,19,20],{},"WSL is Microsoft's Linux subsystem on Windows. WSL1 is a translation layer; WSL2 is a real, lightweight virtual machine built on the Hyper-V kernel, running a full Linux kernel. It has the best compatibility and the highest file-system performance (except when crossing into Windows files).",[10,22,23],{},"Who it is for.",[25,26,27,31,34],"ul",{},[28,29,30],"li",{},"Developers running Node, Python, Go, Rust, Docker, or Linux-only CLI tools.",[28,32,33],{},"Ops or SREs reproducing server environments locally.",[28,35,36],{},"Students or hobbyists learning Linux commands at zero cost.",[10,38,39],{},"It is not for a full desktop to play games or for drivers that only ship as closed-source Linux binaries.",[14,41,43],{"id":42},"one-line-install-recommended","One-line install (recommended)",[10,45,46],{},"Requirements: Windows 10 2004 or later, or Windows 11 (Home included, no Pro needed).",[48,49,50],"ol",{},[28,51,52],{},"Open PowerShell or Windows Terminal as administrator and run.",[54,55,60],"pre",{"className":56,"code":57,"language":58,"meta":59,"style":59},"language-powershell shiki shiki-themes github-light github-dark","wsl --install\n","powershell","",[61,62,63],"code",{"__ignoreMap":59},[64,65,68],"span",{"class":66,"line":67},"line",1,[64,69,57],{},[10,71,72],{},"This single command enables the needed Windows features, installs the default Ubuntu, and pulls the latest kernel.",[48,74,76,79,82],{"start":75},2,[28,77,78],{},"Reboot.",[28,80,81],{},"Open Ubuntu from the Start menu and set a username and password (for Linux, unrelated to your Windows password).",[28,83,84,85,88],{},"Done. Run ",[61,86,87],{},"uname -a"," in the terminal to see the Linux kernel version.",[10,90,91,92,95,96,99],{},"To install another distro, run ",[61,93,94],{},"wsl --list --online"," for the list, then ",[61,97,98],{},"wsl --install -d Debian"," for Debian.",[14,101,103],{"id":102},"manual-enable-if-the-one-line-install-fails","Manual enable (if the one-line install fails)",[48,105,106],{},[28,107,108],{},"In admin PowerShell.",[54,110,112],{"className":56,"code":111,"language":58,"meta":59,"style":59},"dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart\ndism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart\n",[61,113,114,119],{"__ignoreMap":59},[64,115,116],{"class":66,"line":67},[64,117,118],{},"dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart\n",[64,120,121],{"class":66,"line":75},[64,122,123],{},"dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart\n",[48,125,126,128,131,138],{"start":75},[28,127,78],{},[28,129,130],{},"Download and install the WSL2 Linux kernel update package (search \"WSL2 kernel\" on Microsoft's site).",[28,132,133,134,137],{},"Set WSL2 as default with ",[61,135,136],{},"wsl --set-default-version 2",".",[28,139,140,141,137],{},"Install Ubuntu from the Microsoft Store, or ",[61,142,143],{},"wsl --install -d Ubuntu",[10,145,146],{},"If the feature checkbox is greyed out, BIOS virtualization is likely off; start with the Windows Sandbox and Hyper-V article.",[14,148,150],{"id":149},"common-configuration","Common configuration",[152,153,155],"h3",{"id":154},"swap-to-a-faster-package-source-apt","Swap to a faster package source (apt)",[10,157,158,159,162,163,166],{},"Edit ",[61,160,161],{},"/etc/apt/sources.list"," on Ubuntu and switch to a China-based mirror such as USTC, Aliyun, or Tsinghua, then run ",[61,164,165],{},"sudo apt update && sudo apt upgrade -y",". New users can search \"Ubuntu 22.04 Tsinghua source\" and paste.",[152,168,170],{"id":169},"reach-windows-files","Reach Windows files",[25,172,173,187],{},[28,174,175,176,179,180,183,184,137],{},"From Linux, Windows lives under ",[61,177,178],{},"/mnt/c",", ",[61,181,182],{},"/mnt/d",", and so on, for example ",[61,185,186],{},"/mnt/c/Users/yourname/Desktop",[28,188,189,190,193],{},"From Windows, type ",[61,191,192],{},"\\\\wsl$\\Ubuntu\\"," in File Explorer's address bar.",[10,195,196,197,200,201,204,205,137],{},"Cross-system reads and writes are slow, so keep large project files in the Linux home directory (",[61,198,199],{},"~",", that is ",[61,202,203],{},"/home/yourname","), not in ",[61,206,178],{},[152,208,210],{"id":209},"cap-memory-and-cpu-avoid-eating-all-ram","Cap memory and CPU (avoid eating all RAM)",[10,212,213,214,217,218,221],{},"In your user folder (",[61,215,216],{},"C:\\Users\\yourname",") create a file named ",[61,219,220],{},".wslconfig"," with this.",[54,223,227],{"className":224,"code":225,"language":226,"meta":59,"style":59},"language-ini shiki shiki-themes github-light github-dark","[wsl2]\nmemory=4GB\nprocessors=4\nswap=2GB\n","ini",[61,228,229,234,239,245],{"__ignoreMap":59},[64,230,231],{"class":66,"line":67},[64,232,233],{},"[wsl2]\n",[64,235,236],{"class":66,"line":75},[64,237,238],{},"memory=4GB\n",[64,240,242],{"class":66,"line":241},3,[64,243,244],{},"processors=4\n",[64,246,248],{"class":66,"line":247},4,[64,249,250],{},"swap=2GB\n",[10,252,253,254,257],{},"Save, then run ",[61,255,256],{},"wsl --shutdown"," to apply on next start. This matters most when C is low on space.",[152,259,261],{"id":260},"graphical-apps-gui","Graphical apps (GUI)",[10,263,264,265,268],{},"WSL2 supports native Linux GUI through WSLg, built into Windows 11. Just run ",[61,266,267],{},"sudo apt install gedit","; the gedit window pops up natively, no extra X server needed.",[152,270,272],{"id":271},"docker","Docker",[10,274,275,276,278],{},"Install Docker Desktop for Windows and tick \"Use WSL 2 based engine\" in settings. Then ",[61,277,271],{}," inside WSL talks directly to it, far lighter than running Docker inside a VM.",[14,280,282],{"id":281},"wsl-vs-dual-boot-vs-virtual-machines","WSL vs dual-boot vs virtual machines",[284,285,286,308],"table",{},[287,288,289],"thead",{},[290,291,292,296,299,302,305],"tr",{},[293,294,295],"th",{},"Option",[293,297,298],{},"Startup",[293,300,301],{},"Performance",[293,303,304],{},"Talks to Windows",[293,306,307],{},"Best for",[309,310,311,329,346],"tbody",{},[290,312,313,317,320,323,326],{},[314,315,316],"td",{},"WSL2",[314,318,319],{},"Instant",[314,321,322],{},"Near native (in Linux)",[314,324,325],{},"Strong",[314,327,328],{},"Dev, command line first",[290,330,331,334,337,340,343],{},[314,332,333],{},"Dual boot",[314,335,336],{},"Reboot",[314,338,339],{},"Native",[314,341,342],{},"No, separate OS",[314,344,345],{},"Needs exclusive hardware",[290,347,348,351,354,357,360],{},[314,349,350],{},"Hyper-V/VMware",[314,352,353],{},"Slow",[314,355,356],{},"Reduced",[314,358,359],{},"Limited",[314,361,362],{},"Full standalone OS",[10,364,365,366,371],{},"In one line: use WSL2 for development, a VM for full isolation (see ",[367,368,370],"a",{"href":369},"/post/45/","Run Virtual Machines on Windows with Sandbox and Hyper-V","), and dual boot only when you must own the hardware.",[14,373,375],{"id":374},"common-problems","Common problems",[25,377,378,384,387,393,399,407],{},[28,379,380,383],{},[61,381,382],{},"wsl --install"," errors or hangs. Confirm the Windows build is new enough, use admin rights, or download the kernel package manually on a corporate network.",[28,385,386],{},"WSL2 says virtualization is not enabled. Turn on VT-x/SVM in BIOS; see the Windows Sandbox and Hyper-V article.",[28,388,389,392],{},[61,390,391],{},"0x80370102"," will not start. The Hyper-V or Virtual Machine Platform feature is off, or BIOS virtualization is disabled.",[28,394,395,398],{},[61,396,397],{},"wsl"," command not found. The Windows version is too old; upgrade or clean-install Windows 11.",[28,400,401,402,406],{},"Network down or apt slow. Switch to a local mirror, or check corporate proxy; the DNS and proxy ideas in ",[367,403,405],{"href":404},"/post/42/","Browser Can't Open Web Pages, but WeChat Works"," help.",[28,408,409],{},"WSL2 nested virtualization. The November 2026 cumulative update (KB5127936) fixed a prior nested-virtualization fault, so keep current.",[14,411,413],{"id":412},"advanced-tips","Advanced tips",[25,415,416,419,422],{},[28,417,418],{},"VS Code remote development. Install the WSL extension and open project folders right inside the Linux environment.",[28,420,421],{},"Windows Terminal. Free from the Microsoft Store; one tabbed window for PowerShell, CMD, and Ubuntu beats everything else.",[28,423,424],{},"systemd. Newer WSL2 enables systemd by default, so more Linux services run.",[14,426,428],{"id":427},"mount-a-usb-drive-and-switch-distros","Mount a USB drive and switch distros",[25,430,431,441,451,458],{},[28,432,433,434,436,437,440],{},"Reach a host USB or external disk. WSL2 does not see USB devices by default. The simplest route is to drop files on a Windows drive (D, for example) and read them from ",[61,435,182],{},". To mount USB directly, forward it from Windows with the usbipd tool using ",[61,438,439],{},"usbipd wsl attach --busid 1-2","; it is fiddly, so beginners can skip it.",[28,442,443,444,447,448,450],{},"Switch the default distro. ",[61,445,446],{},"wsl --setdefault Debian"," makes Debian the one ",[61,449,397],{}," opens.",[28,452,453,454,457],{},"Remove a distro. ",[61,455,456],{},"wsl --unregister Ubuntu"," deletes that distro and its data; make sure nothing is inside first.",[28,459,460,461,464,465,468],{},"Export and import. ",[61,462,463],{},"wsl --export Ubuntu ubuntu.tar"," backs up; ",[61,466,467],{},"wsl --import"," restores on another machine, handy for moving a dev environment.",[470,471,472],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":59,"searchDepth":75,"depth":75,"links":474},[475,476,477,478,485,486,487,488],{"id":16,"depth":75,"text":17},{"id":42,"depth":75,"text":43},{"id":102,"depth":75,"text":103},{"id":149,"depth":75,"text":150,"children":479},[480,481,482,483,484],{"id":154,"depth":241,"text":155},{"id":169,"depth":241,"text":170},{"id":209,"depth":241,"text":210},{"id":260,"depth":241,"text":261},{"id":271,"depth":241,"text":272},{"id":281,"depth":75,"text":282},{"id":374,"depth":75,"text":375},{"id":412,"depth":75,"text":413},{"id":427,"depth":75,"text":428},"md",{},true,"/post/46",{"description":12},"post/46","1Vhex36LTGh06Om6-u4c8xI0J4jNPbt5MXRupBwjsY8",1794378304023]