윈도우 11/10에 WSL2 우분투 설치하기: wsl --install 오류 코드 해결과 설치 직후 바꿀 설정

기준 환경과 이 글의 범위

이 글은 Windows 11 23H2/24H2와 Windows 10 22H2를 기준으로, 마이크로소프트 스토어로 배포되는 WSL 2.x 버전과 Ubuntu 24.04 LTS를 설치하는 과정을 다룹니다. wsl --install 명령은 Windows 10 버전 2004(빌드 19041) 이상에서만 쓸 수 있습니다. 내 윈도우 버전은 Win+R → winver로 확인할 수 있고, 이보다 오래된 빌드라면 윈도우 업데이트부터 하는 것이 수동 설치 절차를 따라가는 것보다 훨씬 빠릅니다.

WSL2와 듀얼 부팅 중 무엇을 고를지, WSL2로 안 되는 작업(실시간 하드웨어 제어, 커널 모듈 개발 등)이 무엇인지는 WSL2와 듀얼 부팅 비교 글에서 따로 정리했습니다. 이 글은 이미 WSL2로 결정한 사람이 실제로 설치하면서 막히는 지점과, 설치 직후 바꿔 두면 나중에 고생을 덜 하는 설정에 집중합니다.

wsl —install 한 줄이 실제로 하는 일

시작 메뉴에서 PowerShell 또는 터미널을 마우스 오른쪽 버튼으로 눌러 “관리자 권한으로 실행”한 뒤 다음 명령을 입력합니다.

wsl --install

이 명령 하나가 내부적으로 처리하는 작업은 세 가지입니다.

1. “Linux용 Windows 하위 시스템”(Microsoft-Windows-Subsystem-Linux) 선택적 기능을 켭니다. WSL이라는 기능 자체의 토대입니다.
2. “가상 머신 플랫폼”(VirtualMachinePlatform) 선택적 기능을 켭니다. WSL2는 리눅스 커널을 경량 가상 머신에서 실행하기 때문에, 이 기능이 없으면 WSL1으로만 동작하거나 아예 배포판이 시작되지 않습니다.
3. WSL 패키지(리눅스 커널 포함)와 기본 배포판인 Ubuntu를 내려받아 설치합니다.

선택적 기능을 켜는 작업은 재부팅해야 적용됩니다. 그래서 명령이 끝나면 재부팅하라는 안내가 나오고, 재부팅 후 로그인하면 우분투 창이 자동으로 열리면서 배포판 설치가 이어집니다. 창이 열리지 않으면 시작 메뉴에서 “Ubuntu”를 실행하면 됩니다.

여기서 흔한 착각은 “기능은 이미 켜져 있으니 재부팅은 건너뛰어도 되겠지”입니다. 재부팅 전에는 하이퍼바이저가 메모리에 올라오지 않았기 때문에, 이 상태에서 우분투를 실행하면 뒤에서 다룰 0x80370102 같은 오류가 나옵니다. 오류를 검색하기 전에 재부팅을 했는지부터 확인하는 것이 좋습니다.

이미 WSL이 설치된 PC에서 wsl --install을 다시 실행하면 도움말만 출력되고 아무 일도 일어나지 않는 경우가 있습니다. 이때는 배포판을 명시해서 설치합니다.

설치할 배포판 고르기

wsl --install이 기본으로 설치하는 “Ubuntu”는 특정 버전을 가리키는 이름이 아니라, 그때그때 최신 LTS를 따라가는 배포판입니다. 팀에서 버전을 고정해 쓰거나 서버와 같은 버전을 맞추고 싶다면 버전이 붙은 이름으로 설치하는 편이 명확합니다.

# 설치 가능한 배포판 목록 확인
wsl --list --online

# 특정 버전을 지정해서 설치
wsl --install -d Ubuntu-24.04

wsl --list --online(줄여서 wsl -l -o)의 출력에서 왼쪽 열(NAME)에 있는 이름을 -d 뒤에 그대로 쓰면 됩니다. 같은 PC에 Ubuntu-22.04와 Ubuntu-24.04를 나란히 설치하는 것도 가능하며, 각각 독립된 파일 시스템을 갖습니다.

회사 PC처럼 마이크로소프트 스토어 접근이 막혀 있으면 다운로드 단계에서 실패하는 경우가 있습니다. 이때는 스토어를 거치지 않고 GitHub 릴리스에서 직접 내려받는 옵션을 쓸 수 있습니다.

wsl --install --web-download -d Ubuntu-24.04

시작 전 확인: BIOS의 CPU 가상화

WSL2는 가상 머신이므로 CPU의 하드웨어 가상화 기능(인텔 VT-x, AMD-V/SVM)이 BIOS/UEFI에서 켜져 있어야 합니다. 작업 관리자(Ctrl+Shift+Esc) → 성능 → CPU 화면 오른쪽 아래의 “가상화” 항목이 “사용”이면 준비된 상태입니다.

“사용 안 함”으로 나오면 재부팅하면서 BIOS 설정으로 들어가야 합니다. 메뉴 이름은 제조사마다 다르지만 대체로 다음 중 하나입니다.

• 인텔: Intel Virtualization Technology, Intel VT-x, VT-d와 함께 묶여 있는 경우도 있음
• AMD: SVM Mode, AMD-V
• 위치: Advanced, CPU Configuration, Security, Virtualization 메뉴 아래

BitLocker가 켜진 PC에서 BIOS 설정을 바꾸면 다음 부팅 때 복구 키를 요구할 수 있습니다. BIOS에 들어가기 전에 BitLocker 복구 키를 미리 확인해 두십시오. 마이크로소프트 계정에 연결된 PC라면 aka.ms/myrecoverykey에서 볼 수 있습니다.

명령줄로 확인하고 싶다면 systeminfo의 마지막 부분을 봅니다. “Hyper-V 요구 사항” 항목에 “펌웨어에 가상화 사용: 예”가 나오면 켜진 것이고, “하이퍼바이저가 검색되었습니다”라는 문구만 나온다면 이미 하이퍼바이저가 돌고 있다는 뜻이라 가상화도 켜져 있는 것입니다.

설치 중 나오는 오류 코드별 원인과 해결

WSL 설치 오류는 대부분 WslRegisterDistribution failed with error: 뒤에 16진수 코드가 붙는 형태로 나옵니다. 앞부분 문구는 같기 때문에 반드시 뒤의 코드로 원인을 구분해야 합니다.

0x80370102: 가상화가 꺼져 있거나 가상 머신 플랫폼이 없음

Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x80370102
Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.
For information please visit https://aka.ms/enablevirtualization

가장 흔한 오류입니다. 메시지가 말하는 그대로 두 가지 중 하나가 원인입니다.

첫째, BIOS에서 CPU 가상화가 꺼져 있는 경우입니다. 앞 절의 방법으로 작업 관리자에서 확인하고 BIOS에서 켭니다.

둘째, 가상 머신 플랫폼 기능이 켜져 있지 않거나, 켜져 있어도 부팅할 때 하이퍼바이저가 시작되지 않도록 설정된 경우입니다. 관리자 PowerShell에서 다음을 실행하고 재부팅합니다.

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
bcdedit /set hypervisorlaunchtype auto

두 번째 명령은 예전에 다른 가상화 프로그램을 쓰려고 hypervisorlaunchtype off로 꺼 둔 경우를 되돌리는 것입니다. bcdedit /enum | findstr hypervisorlaunchtype으로 현재 값을 확인할 수 있고, 값이 Off라면 기능을 아무리 켜도 하이퍼바이저가 올라오지 않습니다.

윈도우 자체가 VMware나 Hyper-V 같은 가상 머신 안에서 돌고 있는 경우(사내 VDI 등)에는 바깥 하이퍼바이저에서 중첩 가상화(nested virtualization)를 허용해 주지 않으면 이 오류가 계속 납니다. 이건 사용자 쪽에서 해결할 수 없으니 관리자에게 요청해야 합니다.

0x8007019e: WSL 선택적 기능이 꺼져 있음

Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x8007019e
The Windows Subsystem for Linux optional component is not enabled. Please enable it and try again.

스토어에서 Ubuntu 앱만 먼저 설치하고 실행했을 때 자주 봅니다. 배포판 앱은 설치됐지만 그것을 돌릴 WSL 기능이 꺼져 있다는 뜻입니다.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

실행한 뒤 재부팅하고, 이어서 0x80370102를 피하기 위해 가상 머신 플랫폼도 함께 켜져 있는지 확인합니다. 사실 이 두 기능을 각각 켜는 것보다 wsl --install을 다시 실행하는 편이 빠뜨리는 것이 없습니다.

0x800701bc: WSL2 커널 업데이트 필요

WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel

WSL2용 리눅스 커널이 설치되지 않았거나 너무 오래된 경우입니다. 예전에는 커널 업데이트 MSI 패키지를 따로 내려받아 설치해야 했지만, 지금은 다음 명령 하나로 해결됩니다.

wsl --update
wsl --shutdown

wsl --update가 스토어 문제로 실패하면 wsl --update --web-download로 다시 시도합니다. 업데이트 후 wsl --version을 실행했을 때 WSL 버전과 커널 버전이 출력되면 스토어판 WSL이 정상적으로 설치된 것입니다. 이 명령이 “알 수 없는 옵션”이라며 도움말만 출력한다면 아직 윈도우에 내장된 구버전 WSL을 쓰고 있다는 뜻이므로, wsl --update로 스토어판으로 옮겨 가는 것이 좋습니다. 이후에 나오는 .wslconfig의 새 설정들은 스토어판에서만 동작합니다.

그 밖의 WslRegisterDistribution failed

위 세 가지 외의 코드가 나온다면 다음을 순서대로 확인합니다.

• 바이러스 백신이나 보안 소프트웨어가 가상화 관련 프로세스를 막는 경우가 있습니다. 회사 PC라면 보안 정책 때문일 수 있습니다.
• Windows 보안 → 앱 및 브라우저 컨트롤 → 악용 방지 설정에서 시스템 설정의 “제어 흐름 보호(CFG)“를 꺼 둔 경우, 가상 머신 프로세스가 시작되지 못하는 사례가 알려져 있습니다. 직접 바꾼 적이 있다면 기본값으로 되돌립니다.
• 배포판을 압축 해제하는 위치가 NTFS 압축이나 암호화(EFS)된 폴더면 실패할 수 있습니다. %LOCALAPPDATA%\Packages 아래 폴더 속성에서 “내용을 압축하여 디스크 공간 절약”이 켜져 있지 않은지 확인합니다.

”Installing, this may take a few minutes…”에서 멈춤

우분투 창을 처음 열었을 때 이 문구만 뜨고 몇십 분째 진행이 없는 경우입니다. 정상적인 설치는 보통 몇 분 이내에 끝나고 바로 사용자 이름을 묻는 단계로 넘어갑니다.

먼저 창 안에서 Enter 키를 한 번 눌러 봅니다. 콘솔 창이 “선택 모드”(창을 클릭했을 때 커서가 멈추는 상태)에 걸려 출력이 멈춰 있는 경우가 의외로 많습니다. 그래도 그대로라면 창을 닫고 관리자 PowerShell에서 다음 순서로 정리한 뒤 다시 설치합니다.

wsl --shutdown
wsl --update
wsl --unregister Ubuntu-24.04   # 반쯤 등록된 배포판 제거, 아직 데이터가 없을 때만
wsl --install -d Ubuntu-24.04

wsl --unregister는 그 배포판의 파일 시스템 전체를 지우는 명령입니다. 설치가 막 실패한 시점에는 지울 데이터가 없으니 괜찮지만, 이미 쓰던 배포판에 습관처럼 실행하면 안 됩니다.

설치 확인과 WSL1/WSL2 버전 바꾸기

설치가 끝났으면 PowerShell에서 각 배포판이 어떤 WSL 버전으로 돌고 있는지 확인합니다.

wsl -l -v

  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

VERSION 열이 2여야 WSL2입니다. 별표(*)는 그냥 wsl이라고만 입력했을 때 실행되는 기본 배포판을 뜻합니다. 예전에 WSL1을 쓰던 PC거나 0x80370102를 피하려고 WSL1로 설치했던 경우에는 1로 나올 수 있습니다. 다음 명령으로 바꿉니다.

# 이미 설치된 배포판을 WSL2로 변환
wsl --set-version Ubuntu-24.04 2

# 앞으로 설치할 배포판의 기본값을 WSL2로
wsl --set-default-version 2

# 기본 배포판 변경
wsl --set-default Ubuntu-24.04

변환은 파일 시스템 전체를 새 가상 디스크로 옮기는 작업이라 데이터 양에 따라 몇 분 넘게 걸립니다. 변환 도중 0x80370102가 나오면 앞에서 설명한 가상화 설정 문제가 그대로 남아 있는 것입니다.

첫 사용자 만들기와 비밀번호를 잊었을 때

배포판 설치가 끝나면 다음과 같이 리눅스 사용자 이름과 비밀번호를 묻습니다.

Enter new UNIX username:
New password:
Retype new password:

여기서 만드는 계정은 윈도우 계정과 아무 관계가 없는, 우분투 안에서만 쓰는 계정입니다. 윈도우 로그인 이름을 그대로 쓸 필요도 없고, 비밀번호도 다르게 해도 됩니다. 사용자 이름은 소문자로 시작해야 하며 대문자나 공백, 한글을 쓰면 adduser: Please enter a username matching the regular expression 같은 오류가 납니다. 비밀번호는 입력해도 화면에 아무것도 표시되지 않는 것이 정상입니다.

이 계정은 자동으로 sudo 그룹에 들어가므로, sudo apt update처럼 관리자 권한이 필요한 명령을 실행할 때마다 이 비밀번호를 묻습니다. 설치 때 대충 입력하고 잊어버리기 쉬운데, WSL은 윈도우에서 root로 바로 들어가는 길이 있어서 재설치 없이 복구할 수 있습니다.

# PowerShell에서 root로 배포판에 진입
wsl -d Ubuntu-24.04 -u root

# 우분투 안(root 셸)에서 비밀번호 재설정
passwd 사용자이름
exit

반대로 말하면, 윈도우 계정에 접근할 수 있는 사람은 누구나 WSL 배포판의 root가 될 수 있다는 뜻입니다. WSL 안의 리눅스 비밀번호는 윈도우 계정을 보호하는 수단이 아니라는 점을 알아 두는 것이 좋습니다.

설치 단계에서 사용자 생성을 건너뛰어 기본 사용자가 root가 되어 버린 경우에는 adduser로 계정을 만든 뒤, 뒤에서 설명할 /etc/wsl.conf의 [user] 항목에 기본 사용자를 지정합니다.

설치 직후에는 패키지 목록이 오래되어 있으므로 한 번 업데이트해 두는 것이 좋습니다. 우분투 기본 명령은 우분투 필수 명령어 정리에서 다룹니다.

sudo apt update && sudo apt upgrade -y

파일은 어디에 있고, 왜 /mnt/c에서 작업하면 느린가

WSL2에는 파일 시스템이 두 개 있습니다. 우분투 자신의 ext4 파일 시스템(가상 디스크 파일 ext4.vhdx 안에 들어 있음)과, 윈도우 드라이브를 연결해 놓은 /mnt/c, /mnt/d 같은 경로입니다.

윈도우 탐색기에서 우분투 파일에 접근하려면 주소창에 다음 중 하나를 입력합니다.

\\wsl.localhost\Ubuntu-24.04\home\사용자이름
\\wsl$\Ubuntu-24.04\home\사용자이름

\\wsl.localhost가 최근 빌드에서 쓰는 이름이고 \\wsl$는 예전 이름인데, 둘 다 같은 곳을 가리킵니다. 우분투 셸에서 explorer.exe .을 실행하면 현재 디렉터리를 탐색기로 바로 열 수 있습니다. 탐색기 왼쪽 탐색 창에도 “Linux” 항목이 생깁니다.

주의할 점은 ext4.vhdx 파일을 윈도우 쪽에서 직접 열거나 %LOCALAPPDATA% 아래의 배포판 폴더를 윈도우 도구로 수정하지 않는 것입니다. 우분투 파일은 반드시 위의 네트워크 경로나 WSL 안에서 다뤄야 파일 권한과 메타데이터가 깨지지 않습니다.

/mnt/c가 느린 이유

윈도우 드라이브는 WSL2 안에서 9P라는 파일 공유 프로토콜로 연결됩니다. 파일을 열고, 속성을 읽고, 디렉터리를 나열하는 동작 하나하나가 가상 머신 경계를 넘어 윈도우 쪽에 요청을 보내고 응답을 받는 왕복이 됩니다. 큰 파일 하나를 읽을 때는 큰 차이가 없지만, 작은 파일 수만 개를 건드리는 작업에서는 이 왕복 비용이 쌓입니다.

개발 작업이 정확히 그런 패턴입니다. npm install은 node_modules에 수만 개의 파일을 만들고, git status는 모든 파일의 상태를 확인하며, 빌드 도구와 파일 감시자(watcher)는 디렉터리를 계속 훑습니다. 같은 프로젝트를 /mnt/c/Users/...에 두면 우분투 홈 디렉터리에 둘 때보다 눈에 띄게 느려지고, 파일 변경 알림(inotify)이 윈도우 쪽 변경을 제대로 전달받지 못해 핫 리로드가 동작하지 않는 문제도 생깁니다.

그래서 원칙은 단순합니다. 리눅스 도구로 다루는 프로젝트는 ~/projects처럼 우분투 파일 시스템 안에 두고, 윈도우 쪽에서 편집할 때는 뒤에서 설명할 VS Code WSL 연결을 쓰는 것입니다. 반대로 윈도우 프로그램이 주로 다루는 파일(문서, 다운로드 등)은 윈도우 쪽에 두고 가끔 /mnt/c로 읽는 정도가 적당합니다.

이미 /mnt/c에 있는 저장소를 옮길 때는 복사보다 우분투 안에서 새로 git clone하는 편이 줄바꿈 문자(CRLF)와 실행 권한 문제가 섞여 들어오지 않아 깔끔합니다.

.wslconfig: 메모리, CPU, 네트워크 설정

WSL2 가상 머신 전체에 적용되는 설정은 윈도우 사용자 폴더의 .wslconfig 파일에 적습니다. 경로는 C:\Users\<윈도우사용자>\.wslconfig이고, 기본으로는 없으므로 직접 만들어야 합니다. 메모장으로 만들 때는 저장 시 파일 형식을 “모든 파일”로 해야 .wslconfig.txt가 되지 않습니다.

# C:\Users\<윈도우사용자>\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB
networkingMode=mirrored

[experimental]
autoMemoryReclaim=gradual

memory와 processors

기본값으로 WSL2는 윈도우 전체 메모리의 절반까지, CPU는 모든 논리 프로세서를 쓸 수 있습니다. 문제는 리눅스 커널이 남는 메모리를 파일 캐시로 적극적으로 쓰는 성격이라, 큰 빌드나 Docker 이미지 작업을 한 번 하고 나면 작업이 끝나도 작업 관리자에서 VmmemWSL(예전 이름 Vmmem) 프로세스가 수 GB를 계속 붙잡고 있는 것처럼 보인다는 점입니다. 16GB PC에서 8GB를 WSL이 쥐고 있으면 브라우저와 IDE가 버벅이기 시작합니다.

memory로 상한을 두면 이런 상황에서 윈도우 쪽 여유를 보장할 수 있습니다. 다만 너무 낮게 잡으면 우분투 안에서 빌드 도중 프로세스가 OOM으로 강제 종료되므로, 실제로 돌리는 작업의 최대 사용량을 보고 정하는 것이 맞습니다. 우분투 안에서 free -h로 보이는 전체 메모리가 이 값으로 바뀌었는지 확인할 수 있습니다.

autoMemoryReclaim

캐시로 쥐고 있는 메모리를 윈도우에 돌려주게 만드는 설정입니다. gradual은 CPU가 한가할 때 캐시를 조금씩 해제해서 반환하고, dropcache는 한가해지면 캐시를 즉시 비웁니다. disabled가 기본값입니다. 이 설정은 현재 [experimental] 섹션에 속하므로 WSL 버전에 따라 동작이 바뀔 수 있고, 섹션을 잘못 적으면 조용히 무시됩니다. memory 상한과 함께 쓰면 “평소에는 덜 쥐고, 최대로도 이만큼까지만”이라는 두 겹의 제어가 됩니다.

networkingMode=mirrored

기본 네트워크 모드(NAT)에서 WSL2는 윈도우와 다른 내부 IP를 받습니다. 윈도우에서 localhost:3000으로 WSL 안의 개발 서버에 접속하는 것은 자동 포워딩 덕분에 대체로 되지만, 반대로 WSL 안에서 윈도우에 떠 있는 서비스에 localhost로 접속하는 것은 안 되고, 같은 네트워크의 다른 기기(휴대폰 등)에서 WSL 서비스에 접근하려면 netsh interface portproxy로 포워딩을 직접 걸어야 했습니다. VPN을 켜면 WSL 안에서 인터넷이 끊기는 문제도 NAT 모드에서 자주 보고됩니다.

networkingMode=mirrored는 윈도우의 네트워크 인터페이스를 WSL 안에 그대로 비추는 방식입니다. 양방향 localhost가 동작하고, IPv6와 VPN 환경 호환성이 좋아집니다. 이 모드는 Windows 11 22H2 이상에서만 지원되며, Windows 10에서는 설정해도 적용되지 않고 NAT로 동작합니다.

mirrored 모드에서 외부 기기가 WSL 서비스에 접속하려면 윈도우의 Hyper-V 방화벽이 들어오는 연결을 허용해야 합니다. 같은 Wi-Fi의 휴대폰에서 접속이 안 된다면 방화벽 규칙부터 의심하는 것이 맞습니다. 또 WSL 안의 서비스와 윈도우 프로그램이 같은 포트를 쓰려고 하면 이제 충돌이 나므로, 예전에는 문제없던 포트 조합이 갑자기 “address already in use”가 될 수 있습니다.

설정 적용: wsl —shutdown

.wslconfig는 WSL2 가상 머신이 시작될 때만 읽힙니다. 우분투 창을 닫는 것만으로는 가상 머신이 꺼지지 않기 때문에, 파일을 고친 뒤에는 반드시 다음을 실행합니다.

wsl --shutdown

이 명령은 실행 중인 모든 배포판과 가상 머신을 종료합니다. 특정 배포판만 끄려면 wsl --terminate Ubuntu-24.04를 쓰지만, 이 경우 .wslconfig는 다시 읽히지 않습니다. 종료 후 wsl -l -v의 STATE가 Stopped로 바뀐 것을 확인하고 다시 실행하면 새 설정이 적용됩니다.

최근 WSL에는 시작 메뉴에서 “WSL Settings”라는 설정 앱이 함께 설치되어, 위 항목들을 GUI로 바꿀 수도 있습니다. 결과적으로는 같은 .wslconfig 파일을 고치는 것입니다.

/etc/wsl.conf: 배포판별 설정과 systemd

.wslconfig가 가상 머신 전체 설정이라면, /etc/wsl.conf는 배포판 하나에만 적용되는 설정이며 우분투 안에 있습니다.

sudo nano /etc/wsl.conf

[boot]
systemd=true

[user]
default=사용자이름

[interop]
appendWindowsPath=false

systemd 켜기

예전 WSL은 systemd 없이 자체 init으로 부팅했기 때문에 systemctl start docker 같은 명령이 System has not been booted with systemd as init system (PID 1). Can't operate. 오류를 냈습니다. 지금은 [boot] systemd=true로 systemd를 켤 수 있고, 최근 wsl --install로 설치한 Ubuntu는 이 값이 이미 들어 있는 경우가 많습니다. 파일을 먼저 열어 보고 없을 때만 추가하면 됩니다.

systemd가 실제로 PID 1로 떠 있는지는 다음으로 확인합니다.

ps -p 1 -o comm=
# systemd 가 출력되면 정상

systemd를 켜면 Docker, PostgreSQL, SSH 서버처럼 서비스로 관리되는 프로그램을 일반 우분투 서버와 똑같이 systemctl enable로 등록할 수 있습니다. 대신 배포판 시작 시간이 조금 늘고, 서비스들이 떠 있는 만큼 메모리를 더 씁니다.

기본 사용자와 PATH

[user] default는 배포판을 열었을 때 로그인할 사용자를 정합니다. 뒤에서 설명할 import로 배포판을 옮기면 기본 사용자가 root로 바뀌므로, 이 항목을 적어 두면 그 문제를 미리 막을 수 있습니다.

[interop] appendWindowsPath=false는 윈도우의 PATH가 우분투 PATH 뒤에 자동으로 붙는 것을 끕니다. 기본 동작에서는 우분투 안에서 code, explorer.exe를 바로 실행할 수 있어 편하지만, 윈도우 PATH의 폴더 수십 개가 /mnt/c 경유로 붙기 때문에 셸에서 명령을 탭으로 자동완성할 때 눈에 띄게 느려지고, 윈도우에 설치된 node나 python이 우분투 것보다 먼저 잡히는 혼란도 생깁니다. 이 값을 끄면 code 명령도 사라지므로, VS Code 경로만 ~/.bashrc에서 직접 추가하는 방식이 깔끔합니다.

# ~/.bashrc 예시. 윈도우 사용자 이름에 맞게 경로 수정
export PATH="$PATH:/mnt/c/Users/<윈도우사용자>/AppData/Local/Programs/Microsoft VS Code/bin"

/etc/wsl.conf도 배포판이 다시 시작될 때 읽히므로 수정 후에는 PowerShell에서 wsl --shutdown을 실행합니다. 이때 흔히 겪는 일이, 고친 직후 곧바로 우분투를 다시 열면 설정이 반영되지 않은 것처럼 보이는 경우입니다. 가상 머신이 완전히 내려가는 데 몇 초가 걸리므로 wsl -l -v로 Stopped를 확인한 뒤 여는 습관을 들이면 헷갈리지 않습니다.

VS Code에서 WSL에 연결하기

VS Code는 윈도우에 설치하고, 확장 마켓에서 Microsoft가 만든 “WSL” 확장(예전 이름 Remote - WSL)을 설치합니다. 우분투 안에 리눅스용 VS Code를 따로 설치할 필요는 없습니다.

cd ~/projects/my-app
code .

우분투 셸에서 code .을 처음 실행하면 우분투 쪽에 VS Code Server가 자동으로 설치되고, 윈도우의 VS Code 창이 열리면서 왼쪽 아래에 “WSL: Ubuntu-24.04”가 표시됩니다. 이 구조에서는 화면과 입력만 윈도우에서 처리하고, 파일 읽기, 터미널, 확장(린터, 언어 서버, 디버거)은 모두 우분투 안에서 실행됩니다. 그래서 앞에서 말한 9P 경유 성능 문제가 생기지 않고, 언어 서버가 우분투에 설치된 Node.js나 Python을 그대로 인식합니다.

자주 하는 실수는 윈도우 VS Code에서 \\wsl.localhost\... 경로를 “폴더 열기”로 여는 것입니다. 파일은 보이지만 이 경우 VS Code와 확장은 윈도우에서 돌고 파일만 네트워크 경로로 읽기 때문에 느리고, 터미널도 윈도우 PowerShell이 열립니다. 왼쪽 아래에 “WSL” 표시가 없다면 이 상태입니다. 확장은 윈도우 쪽과 WSL 쪽에 따로 설치되므로, WSL 창에서 확장 탭을 열어 “WSL: Ubuntu-24.04에 설치”를 눌러야 하는 것도 처음에 헷갈리는 부분입니다. VS Code를 우분투에서 쓰는 요령은 우분투 VS Code 개발 팁에 더 정리했습니다.

다른 드라이브로 옮기기와 완전히 제거하기

WSL 배포판은 기본으로 C 드라이브의 사용자 폴더 아래에 가상 디스크로 저장됩니다. Docker 이미지와 node_modules가 쌓이면 이 파일이 수십 GB로 커지는데, 안의 파일을 지워도 가상 디스크 크기는 자동으로 줄어들지 않습니다. C 드라이브가 좁다면 export/import로 다른 드라이브로 옮길 수 있습니다.

# 1. 배포판 종료
wsl --shutdown

# 2. 현재 배포판을 tar 파일로 내보내기
wsl --export Ubuntu-24.04 D:\backup\ubuntu-24.04.tar

# 3. 기존 배포판 등록 해제 (C 드라이브의 가상 디스크 삭제)
wsl --unregister Ubuntu-24.04

# 4. 새 위치에 가져오기
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\backup\ubuntu-24.04.tar

3단계에서 원본이 삭제되므로, unregister 전에 export한 tar 파일의 크기가 0이 아닌지 반드시 확인하십시오. 디스크 공간이 부족해 export가 중간에 실패했는데 그대로 unregister하면 데이터를 되살릴 방법이 없습니다.

import로 가져온 배포판은 기본 사용자 정보가 없어 root로 로그인됩니다. 앞에서 설명한 /etc/wsl.conf의 [user] default=사용자이름을 넣고 wsl --shutdown 후 다시 열면 원래 계정으로 돌아옵니다. 또 import한 배포판은 시작 메뉴의 “Ubuntu 24.04” 앱 아이콘과 연결이 끊기므로, 터미널이나 wsl -d Ubuntu-24.04로 실행해야 합니다.

최근 WSL에는 이 과정을 한 번에 해 주는 wsl --manage Ubuntu-24.04 --move D:\WSL\Ubuntu-24.04 명령이 추가되었습니다. wsl --help에 --manage가 보이면 쓸 수 있고, 보이지 않으면 위의 export/import 방식을 쓰면 됩니다. export한 tar 파일은 그 자체로 백업이기도 해서, 큰 설정 변경 전에 한 번 떠 두면 문제가 생겼을 때 import로 이전 상태를 되살릴 수 있습니다.

배포판 하나 삭제, WSL 전체 제거

특정 배포판을 지우려면 wsl --unregister <이름>입니다. 시작 메뉴의 Ubuntu 앱을 “제거”하는 것만으로는 등록된 배포판 데이터가 남는 경우가 있으므로 이 명령으로 정리하는 편이 확실합니다. 나중에 같은 이름으로 다시 설치하면 사용자 생성부터 새로 시작하는 깨끗한 상태가 됩니다.

WSL 자체를 걷어내려면 배포판을 모두 unregister한 뒤 wsl --uninstall로 WSL 패키지를 제거하고, “Windows 기능 켜기/끄기”에서 “Linux용 Windows 하위 시스템”과 “가상 머신 플랫폼”의 체크를 해제한 다음 재부팅합니다. 가상 머신 플랫폼을 끄면 하이퍼바이저가 내려가므로, 하이퍼바이저와 충돌하던 구버전 가상화 프로그램이나 일부 게임 안티치트가 다시 정상 동작하는 경우도 있습니다. 반대로 Docker Desktop이나 Windows 샌드박스처럼 이 기능에 기대는 프로그램은 동작하지 않게 됩니다.

설치를 마쳤다면 다음 단계는 우분투 셸에 익숙해지는 것입니다. 윈도우 습관과 리눅스 습관이 부딪히는 지점(대소문자 구분 경로, 실행 권한, 패키지 관리 방식)은 윈도우 개발자를 위한 우분투 적응 가이드에서 이어서 볼 수 있습니다.