WINDOWS 11 / WINDOWS 10 / WSL2 / UBUNTU

WSL2(Windows Subsystem for Linux) 설치 및 윈도우에서 리눅스 환경 구축하기

윈도우에서 Ubuntu 실행부터 WSL2 설치 오류 해결, VS Code 연결, 개발 환경 설정까지

윈도우를 사용하면서 리눅스 명령어, Python 개발 환경, Git, Node.js, Docker 등을 활용하려면 별도의 리눅스 컴퓨터가 필요하다고 생각하기 쉽습니다. 하지만 Windows Subsystem for Linux, 줄여서 WSL을 이용하면 윈도우 안에서 리눅스 배포판을 실행할 수 있습니다. 특히 WSL2는 실제 리눅스 커널을 활용하는 구조로, 다양한 개발 도구와 높은 호환성을 제공합니다. 이 글에서는 WSL2 설치 전 확인 사항부터 Ubuntu 설치, 기본 명령어, 파일 관리, VS Code 연동, 네트워크 설정, 대표적인 오류 해결 방법까지 순서대로 알아보겠습니다.

설치 명령어

wsl --install

추천 배포판

Ubuntu LTS

사전 확인

Windows 버전·가상화

활용 분야

개발·서버·리눅스 학습

설치 전 반드시 확인할 사항

WSL2를 설치하려면 지원되는 Windows 버전과 CPU 가상화 기능이 필요합니다. 일반적인 설치 방법은 Windows 11 또는 WSL2를 지원하는 Windows 10 환경을 기준으로 합니다.

회사나 학교에서 관리하는 PC는 보안 정책으로 WSL 또는 가상화 기능이 제한될 수 있습니다. BIOS·UEFI 설정 변경이나 Windows 기능 활성화는 관리자 권한과 조직 정책을 확인한 뒤 진행해야 합니다.

WSL 배포판 삭제 명령인 wsl --unregister는 해당 배포판의 파일과 설정을 삭제할 수 있습니다. 문제 해결을 위해 무작정 실행하지 말고 중요한 데이터는 먼저 백업해야 합니다.

1. WSL2란 무엇이며 어떤 장점이 있나요?

WSL은 Windows Subsystem for Linux의 약자로, 윈도우에서 리눅스 환경을 실행할 수 있도록 제공되는 기능입니다. WSL2는 경량 가상화 기술과 실제 리눅스 커널을 활용하여 다양한 리눅스 프로그램을 실행할 수 있도록 지원합니다.

① WSL의 기본 개념

WSL을 이용하면 윈도우를 종료하거나 운영체제를 교체하지 않고도 Ubuntu 같은 리눅스 배포판을 실행할 수 있습니다.

PowerShell, Windows Terminal 등에서 리눅스 셸을 실행하고 리눅스 명령어와 개발 도구를 사용할 수 있습니다.

② WSL1과 WSL2의 차이

WSL1은 리눅스 시스템 호출을 Windows 환경에 맞게 처리하는 구조를 사용합니다.

WSL2는 실제 리눅스 커널을 활용하므로 리눅스 프로그램과의 호환성이 일반적으로 더 높습니다.

비교 항목	WSL1	WSL2
리눅스 커널	실제 커널 미사용	실제 리눅스 커널 사용
가상화 요구	WSL2보다 적음	가상화 기능 필요
리눅스 호환성	일부 제한	일반적으로 높음
리눅스 파일 시스템 성능	작업에 따라 다름	리눅스 파일 내부 작업에 유리
추천 용도	특정 호환성·운영 조건	일반적인 리눅스 개발 환경

③ 가상 머신과의 차이

일반적인 가상 머신은 별도의 가상 하드웨어와 운영체제를 구성하여 실행합니다.

WSL2도 가상화 기술을 사용하지만 Windows와 통합된 경량 환경을 제공하므로 리눅스 개발 도구를 비교적 간편하게 사용할 수 있습니다.

④ 듀얼 부팅과의 차이

듀얼 부팅은 컴퓨터 시작 시 Windows와 Linux 중 사용할 운영체제를 선택하는 방식입니다.

WSL2는 Windows를 실행한 상태에서 Linux를 사용할 수 있어 운영체제를 전환하기 위해 재부팅할 필요가 없습니다.

⑤ Ubuntu를 사용하는 이유

Ubuntu는 널리 사용되는 리눅스 배포판으로 문서와 학습 자료가 풍부합니다.

패키지 관리 도구인 apt를 통해 다양한 개발 프로그램을 설치할 수 있어 입문자가 사용하기 좋습니다.

⑥ WSL2로 할 수 있는 작업

리눅스 명령어 학습, Python 개발, Node.js 개발, Git 사용, 셸 스크립트 작성, 로컬 웹 서버 실행, Docker 기반 개발 환경 구축 등에 활용할 수 있습니다.

⑦ Windows 파일에 접근할 수 있나요?

WSL에서는 일반적으로 Windows 드라이브가 /mnt 아래에 연결됩니다.

예를 들어 Windows의 C 드라이브는 Ubuntu에서 /mnt/c 경로로 접근할 수 있습니다.

⑧ Windows 프로그램과 함께 사용할 수 있나요?

WSL에서는 Windows와 Linux 도구를 연계하여 사용할 수 있습니다.

지원되는 환경에서는 Linux GUI 프로그램도 실행할 수 있으며, Windows 편집기와 Linux 개발 도구를 조합하는 것도 가능합니다.

⑨ 모든 리눅스 작업을 완벽하게 지원하나요?

WSL2는 호환성이 높지만 일반적인 물리 리눅스 설치와 완전히 동일하지는 않습니다.

특정 하드웨어 장치, 커널 모듈, 저수준 네트워크 기능 또는 특수 시스템 서비스는 별도 설정이나 다른 환경이 필요할 수 있습니다.

⑩ WSL2가 적합한 사용자

Windows를 기본 운영체제로 유지하면서 리눅스 개발 환경을 사용하려는 개발자, 학생, 서버 관리 학습자에게 유용합니다.

다만 실제 서버 운영 환경과 완전히 동일한 조건이 필요하다면 별도의 Linux 서버나 가상 머신을 검토할 수 있습니다.

핵심 정리

일반적인 Windows 기반 개발 환경이라면 WSL2와 Ubuntu LTS를 조합하는 것이 좋은 출발점입니다. Windows 프로그램을 그대로 사용하면서 Linux 터미널과 개발 도구를 활용할 수 있습니다.

2. WSL2 설치 전 Windows 및 가상화 확인

WSL2 설치 오류는 Windows 버전, 가상화 기능, 관리자 권한, 재부팅 누락 때문에 발생하는 경우가 많습니다. 설치 명령어를 실행하기 전에 시스템 상태를 확인하면 문제를 줄일 수 있습니다.

① Windows 버전 확인

Win + R 키를 누른 뒤 다음 명령을 입력합니다.

winver

Windows 버전과 빌드 정보를 확인합니다.

② Windows 11 지원 여부

지원되는 Windows 11 환경에서는 일반적으로 wsl --install 명령으로 WSL 설치를 시작할 수 있습니다.

시스템 정책이나 가상화 설정에 따라 추가 작업이 필요할 수 있습니다.

③ Windows 10 지원 여부

WSL2는 Windows 10 버전 2004 이상, 빌드 19041 이상에서 지원됩니다.

간편 설치 명령의 지원 범위는 Windows 업데이트 수준에 따라 달라질 수 있으므로 Microsoft 공식 설치 문서를 확인하는 것이 좋습니다.

Windows 10의 일반 지원은 2025년 10월 14일 종료되었으므로 보안 업데이트를 받을 수 있는 지원 상태도 함께 확인해야 합니다.

④ CPU 가상화 지원 확인

Ctrl + Shift + Esc 키로 작업 관리자를 실행합니다.

성능 → CPU 화면에서 가상화 항목을 확인합니다.

가상화가 활성화되어 있다면 해당 항목에 사용 가능 상태가 표시될 수 있습니다.

⑤ 가상화가 비활성화된 경우

CPU가 가상화를 지원하지만 비활성화되어 있다면 BIOS 또는 UEFI 설정에서 활성화해야 할 수 있습니다.

제조사에 따라 Intel Virtualization Technology, Intel VT-x, AMD-V, SVM Mode 등의 이름으로 표시됩니다.

설정 위치는 메인보드와 컴퓨터 제조사마다 다릅니다.

⑥ 관리자 권한 PowerShell 실행

시작 메뉴에서 PowerShell 또는 Windows Terminal을 검색한 뒤 관리자 권한으로 실행합니다.

WSL 설치와 Windows 선택적 기능 활성화에는 관리자 권한이 필요할 수 있습니다.

⑦ 기존 WSL 설치 상태 확인

다음 명령을 실행합니다.

wsl --status

WSL의 기본 설정과 관련 상태를 확인할 수 있습니다.

⑧ 설치된 배포판 확인

다음 명령을 실행합니다.

wsl --list --verbose

설치된 배포판과 실행 상태, WSL 버전을 확인할 수 있습니다.

⑨ Windows 기능 확인

WSL2에는 일반적으로 Windows Subsystem for Linux와 Virtual Machine Platform 기능이 사용됩니다.

지원되는 시스템에서 wsl --install을 실행하면 필요한 기능을 자동으로 활성화할 수 있습니다.

⑩ Hyper-V 전체 기능이 필요한가요?

WSL2를 사용하기 위해 반드시 Windows의 전체 Hyper-V 관리 기능을 설치할 필요는 없습니다.

WSL2에 필요한 가상화 구성 요소와 전체 Hyper-V 관리 기능은 구분해야 합니다.

⑪ 저장 공간 확인

WSL2 배포판은 리눅스 파일 시스템을 저장하기 위한 가상 디스크 파일을 사용합니다.

배포판 설치뿐 아니라 패키지 업데이트, 프로젝트 파일, 개발 도구를 위한 여유 공간도 필요합니다.

⑫ 회사·학교 PC 사용 시 주의

조직에서 관리하는 컴퓨터는 가상화나 Windows 선택적 기능 변경이 제한될 수 있습니다.

보안 정책을 임의로 우회하지 말고 시스템 관리자에게 WSL 사용 가능 여부를 확인해야 합니다.

설치 전 빠른 점검

winver로 Windows 버전을 확인합니다.
작업 관리자에서 CPU 가상화 상태를 확인합니다.
관리자 권한으로 PowerShell을 실행합니다.
wsl --status로 기존 WSL 상태를 확인합니다.
wsl --list --verbose로 기존 배포판을 확인합니다.
필요한 저장 공간과 조직의 사용 정책을 확인합니다.

3. WSL2 및 Ubuntu 설치하는 방법

지원되는 최신 Windows 환경에서는 WSL 설치가 비교적 간단합니다. 기본 설치 명령어를 사용하면 필요한 구성 요소와 기본 리눅스 배포판을 함께 설치할 수 있습니다.

① PowerShell 관리자 권한 실행

시작 메뉴에서 PowerShell을 검색하고 관리자 권한으로 실행합니다.

이미 WSL이 설치된 경우에는 현재 상태를 먼저 확인한 뒤 필요한 작업만 수행하는 것이 좋습니다.

② WSL 설치 명령어 실행

다음 명령을 입력합니다.

wsl --install

지원되는 환경에서는 WSL 구성 요소와 기본 배포판인 Ubuntu를 설치하도록 진행됩니다.

③ 설치 후 Windows 재부팅

설치 과정에서 재부팅을 요청하면 작업 중인 파일을 저장한 뒤 Windows를 재시작합니다.

재부팅이 필요한 상황에서 이를 생략하면 WSL 실행 오류가 발생할 수 있습니다.

④ 설치 가능한 배포판 목록 확인

특정 배포판을 선택하려면 다음 명령을 실행합니다.

wsl --list --online

현재 설치 가능한 리눅스 배포판 목록을 확인할 수 있습니다.

⑤ Ubuntu를 지정하여 설치

목록에 Ubuntu가 표시된다면 다음 명령으로 설치할 수 있습니다.

wsl --install -d Ubuntu

특정 Ubuntu LTS 버전을 설치하고 싶다면 온라인 목록에 표시되는 정확한 배포판 이름을 사용합니다.

⑥ 다운로드가 진행되지 않는 경우

Microsoft Store 관련 다운로드에 문제가 있다면 지원되는 WSL 환경에서 다음 명령을 시도할 수 있습니다.

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

이 옵션은 지원되는 환경에서 온라인 다운로드 경로를 변경하는 데 도움이 될 수 있습니다. 인터넷 연결과 조직의 네트워크 정책에 따라 결과가 달라질 수 있습니다.

⑦ Ubuntu 최초 실행

설치가 완료되면 시작 메뉴에서 Ubuntu를 실행하거나 다음 명령을 사용합니다.

wsl -d Ubuntu

설치한 배포판 이름이 다르다면 실제 이름으로 변경해야 합니다.

⑧ 리눅스 사용자 이름 생성

Ubuntu 최초 실행 시 리눅스 사용자 이름을 입력하도록 안내할 수 있습니다.

Windows 계정과 별도로 관리되는 사용자 계정입니다.

일반적으로 영문 소문자와 숫자 등을 이용한 간단한 사용자 이름을 지정합니다.

⑨ 리눅스 사용자 비밀번호 설정

사용자 계정을 생성할 때 비밀번호를 설정합니다.

터미널에서는 비밀번호를 입력해도 문자나 별표가 화면에 표시되지 않을 수 있습니다.

이는 정상적인 동작이며 비밀번호를 입력한 뒤 Enter 키를 누르면 됩니다.

⑩ 설치된 WSL 버전 확인

Windows 터미널에서 다음 명령을 실행합니다.

wsl -l -v

Ubuntu의 VERSION 열이 2로 표시되는지 확인합니다.

⑪ 기본 WSL 버전을 2로 설정

앞으로 새로 설치할 배포판의 기본 WSL 버전을 2로 지정하려면 다음 명령을 사용합니다.

wsl --set-default-version 2

이 명령은 이미 설치된 모든 배포판을 자동으로 변환하는 명령은 아닙니다.

⑫ 기존 Ubuntu를 WSL2로 변환

기존 배포판이 WSL1로 표시된다면 다음 명령으로 WSL2 변환을 진행할 수 있습니다.

wsl --set-version Ubuntu 2

변환 전에는 중요한 파일을 백업하고 저장 공간을 확인하는 것이 좋습니다.

⑬ 기본 배포판 설정

여러 배포판이 설치되어 있다면 기본으로 실행할 배포판을 지정할 수 있습니다.

wsl --set-default Ubuntu

⑭ WSL 업데이트

WSL 구성 요소를 업데이트하려면 Windows PowerShell에서 다음 명령을 실행합니다.

wsl --update

이 명령은 WSL 자체를 업데이트하는 명령입니다. Ubuntu 내부 패키지 업데이트는 별도로 진행해야 합니다.

⑮ 설치 완료 확인

Ubuntu 터미널에서 다음 명령을 실행합니다.

uname -a
cat /etc/os-release
pwd
whoami

리눅스 커널 정보, 배포판 정보, 현재 경로, 사용자 이름이 표시되면 기본적인 실행 상태를 확인할 수 있습니다.

WSL2 설치 핵심 명령어 모음

# Windows PowerShell에서 실행

wsl --status
wsl --list --online
wsl --install -d Ubuntu

# 필요 시 Windows 재부팅

wsl --set-default-version 2
wsl -l -v
wsl --update
wsl -d Ubuntu

위 명령어는 설치 및 상태 확인에 사용하는 예시입니다. 이미 Ubuntu가 설치된 경우에는 중복 설치를 시도하기보다 현재 배포판과 버전을 먼저 확인하세요.

4. Ubuntu 초기 설정과 리눅스 기본 명령어

WSL2 설치를 완료했다면 Ubuntu 내부의 패키지를 업데이트하고 기본 명령어를 익혀야 합니다. Windows PowerShell 명령어와 Ubuntu 셸 명령어는 실행 환경이 다르므로 구분해서 사용해야 합니다.

① Ubuntu 패키지 목록 업데이트

Ubuntu 터미널에서 다음 명령을 실행합니다.

sudo apt update

설정된 패키지 저장소에서 최신 패키지 목록을 가져옵니다.

② 설치된 패키지 업그레이드

다음 명령으로 업데이트 가능한 패키지를 업그레이드합니다.

sudo apt upgrade

업그레이드 대상과 변경 내용을 확인한 뒤 진행합니다.

③ sudo 명령어 이해하기

sudo는 권한이 필요한 작업을 수행할 때 사용합니다.

패키지 설치나 시스템 설정 변경에 주로 사용하며, 일반 파일 작업까지 무조건 sudo를 붙일 필요는 없습니다.

④ 현재 경로 확인

다음 명령을 실행합니다.

pwd

현재 작업 중인 디렉터리의 전체 경로를 확인할 수 있습니다.

⑤ 파일과 폴더 목록 확인

다음 명령으로 파일과 폴더를 확인합니다.

ls
ls -la

ls -la는 숨김 파일과 권한 등 상세 정보를 함께 보여줍니다.

⑥ 디렉터리 이동

다음 명령을 사용합니다.

cd ~
cd /mnt/c

cd ~는 현재 사용자의 홈 디렉터리로 이동하고, cd /mnt/c는 일반적인 WSL 설정에서 Windows C 드라이브로 이동합니다.

⑦ 프로젝트 폴더 만들기

Ubuntu 홈 디렉터리에 개발용 폴더를 생성합니다.

mkdir -p ~/projects
cd ~/projects

리눅스 도구로 작업하는 프로젝트는 일반적으로 Ubuntu 파일 시스템 내부에 저장하는 것이 파일 처리 성능 측면에서 유리합니다.

⑧ 파일 생성과 내용 확인

다음 명령으로 간단한 파일을 생성할 수 있습니다.

echo "Hello WSL2" > hello.txt
cat hello.txt

⑨ 파일 복사와 이동

파일을 복사하거나 이름을 변경할 때 다음 명령을 사용할 수 있습니다.

cp hello.txt hello-backup.txt
mv hello-backup.txt hello-copy.txt

⑩ 파일 삭제 시 주의

Linux의 rm 명령은 파일을 삭제합니다.

삭제한 파일은 일반적인 Windows 휴지통으로 이동하지 않을 수 있으므로 경로를 확인해야 합니다.

rm -i hello-copy.txt

-i 옵션은 삭제 전 확인을 요청합니다.

⑪ Windows 탐색기에서 Ubuntu 파일 열기

Ubuntu 터미널에서 다음 명령을 실행합니다.

explorer.exe .

현재 Linux 디렉터리를 Windows 파일 탐색기로 열 수 있습니다.

⑫ Windows에서 WSL 파일 접근

Windows 파일 탐색기 주소 표시줄에 다음 경로를 입력할 수 있습니다.

\\wsl$\Ubuntu

배포판 이름은 실제 설치된 이름과 일치해야 합니다.

지원되는 환경에서는 \\wsl.localhost\Ubuntu 경로도 사용할 수 있습니다.

⑬ WSL 파일 시스템 주의 사항

WSL2의 Linux 파일은 가상 디스크 내부에 저장됩니다.

Windows에서 가상 디스크 파일을 직접 수정하거나 내부 파일 구조를 강제로 변경하면 데이터가 손상될 수 있습니다.

Linux 파일에 접근할 때는 WSL 터미널이나 공식적으로 지원되는 탐색기 경로를 사용하는 것이 좋습니다.

⑭ Windows 프로그램 실행

WSL 터미널에서 일부 Windows 실행 파일을 호출할 수 있습니다.

notepad.exe hello.txt

실행 환경과 파일 접근 권한에 따라 동작이 달라질 수 있습니다.

⑮ Ubuntu 종료 및 WSL 종료

현재 Linux 셸을 종료하려면 다음 명령을 실행합니다.

exit

WSL 전체를 종료하려면 Windows PowerShell에서 다음 명령을 실행합니다.

wsl --shutdown

이 명령은 실행 중인 모든 WSL 배포판과 WSL2 가상 머신을 종료하므로 진행 중인 작업을 저장한 뒤 사용합니다.

Linux 명령어	기능
`pwd`	현재 디렉터리 확인
`ls -la`	파일 목록 상세 확인
`cd`	디렉터리 이동
`mkdir`	폴더 생성
`cp`	파일 복사
`mv`	파일 이동·이름 변경
`cat`	파일 내용 출력
`sudo apt update`	패키지 목록 갱신
`sudo apt upgrade`	패키지 업그레이드
`exit`	현재 셸 종료

5. VS Code·Git·Python·Node.js 개발 환경 구축

WSL2를 설치한 뒤 개발 도구를 연결하면 Windows에서 편집기를 사용하면서 Linux 환경에서 프로그램을 실행할 수 있습니다. 대표적으로 Visual Studio Code, Git, Python, Node.js 등을 함께 활용할 수 있습니다.

① Visual Studio Code 설치

Windows에 Visual Studio Code를 설치합니다.

공식 다운로드 주소는 다음과 같습니다.

https://code.visualstudio.com/

② WSL 확장 프로그램 설치

VS Code의 확장 프로그램 화면에서 Microsoft의 WSL 확장을 검색하여 설치합니다.

이 확장은 Windows의 VS Code에서 WSL 내부 개발 환경에 연결할 수 있도록 지원합니다.

③ Ubuntu 프로젝트 폴더 생성

Ubuntu 터미널에서 다음 명령을 실행합니다.

mkdir -p ~/projects/hello-wsl
cd ~/projects/hello-wsl

④ VS Code에서 WSL 폴더 열기

다음 명령을 실행합니다.

code .

VS Code와 WSL 연동이 정상적으로 구성되어 있다면 현재 폴더를 WSL 개발 환경으로 열 수 있습니다.

⑤ WSL 연결 상태 확인

VS Code에서 원격 연결 상태가 WSL로 표시되는지 확인합니다.

통합 터미널을 열어 다음 명령을 실행합니다.

uname -a
pwd

Linux 커널 정보와 WSL 내부 프로젝트 경로가 표시되면 연결 상태를 확인할 수 있습니다.

⑥ Git 설치

Ubuntu에서 다음 명령으로 Git을 설치할 수 있습니다.

sudo apt update
sudo apt install git

설치 후 다음 명령으로 확인합니다.

git --version

⑦ WSL 내부 Git 사용자 정보 설정

Windows에 설치된 Git과 WSL 내부의 Git은 설정이 별도로 관리될 수 있습니다.

Ubuntu 터미널에서 다음 명령을 실행합니다.

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

실제 사용하는 이름과 이메일로 변경해야 합니다.

⑧ Python 설치 상태 확인

Ubuntu에서 다음 명령을 실행합니다.

python3 --version

Python이 설치되어 있다면 버전이 표시됩니다.

⑨ Python 개발 도구 설치

필요한 경우 다음 명령으로 Python과 가상 환경 도구를 설치합니다.

sudo apt update
sudo apt install python3 python3-venv python3-pip

⑩ Python 가상 환경 생성

프로젝트별 패키지를 분리하기 위해 가상 환경을 사용할 수 있습니다.

cd ~/projects/hello-wsl
python3 -m venv .venv
source .venv/bin/activate

가상 환경이 활성화되면 해당 환경에 필요한 Python 패키지를 설치할 수 있습니다.

⑪ Python 테스트 프로그램 실행

다음 명령을 실행합니다.

python -c "print('Hello from WSL2')"

가상 환경이 활성화된 상태에서 메시지가 출력되면 기본적인 Python 실행을 확인할 수 있습니다.

⑫ Node.js 설치 방법

Node.js 개발 환경은 프로젝트에서 요구하는 버전에 맞춰 설치하는 것이 좋습니다.

여러 Node.js 버전을 사용하는 경우에는 nvm 같은 버전 관리 도구를 검토할 수 있습니다.

공식 안내를 확인한 뒤 신뢰할 수 있는 설치 절차를 사용해야 합니다.

Node.js 공식 설치 안내

⑬ Node.js 설치 확인

설치 후 다음 명령을 실행합니다.

node --version
npm --version

⑭ Docker와 WSL2

Docker Desktop은 지원되는 Windows 환경에서 WSL2 백엔드와 통합하여 사용할 수 있습니다.

Docker Desktop 설정에서 WSL 통합 기능을 확인해야 하며, 조직 또는 상업적 사용에서는 라이선스 조건도 확인해야 합니다.

⑮ 로컬 웹 서버 테스트

Ubuntu의 프로젝트 폴더에서 Python을 이용한 간단한 HTTP 서버를 실행할 수 있습니다.

cd ~/projects/hello-wsl
python3 -m http.server 8000 --bind 127.0.0.1

지원되는 기본 WSL 네트워크 환경에서는 Windows 브라우저에서 다음 주소로 접근할 수 있습니다.

http://localhost:8000

테스트가 끝나면 터미널에서 Ctrl + C로 서버를 종료합니다.

⑯ 프로젝트 파일 위치 선택

Linux 도구로 주로 작업한다면 ~/projects처럼 WSL 내부 파일 시스템을 사용하는 것이 일반적으로 권장됩니다.

Windows 프로그램에서 주로 사용하는 파일은 Windows 드라이브에 저장하는 편이 적합할 수 있습니다.

작업 도구와 파일 접근 패턴에 따라 위치를 결정해야 합니다.

WSL2 개발 환경 추천 구성

Windows Terminal: PowerShell과 Ubuntu 터미널 관리
Ubuntu LTS: 리눅스 개발 및 패키지 관리
Visual Studio Code: 코드 편집과 WSL 원격 연결
Git: 소스 코드 버전 관리
Python 가상 환경: 프로젝트별 Python 패키지 분리
Node.js 버전 관리 도구: 프로젝트별 Node.js 버전 관리
Docker Desktop: 필요한 경우 컨테이너 개발 환경 구성

6. WSL2 설치 오류 및 실행 문제 해결

WSL2 설치 과정에서 오류가 발생한다면 Windows 기능, 가상화, WSL 업데이트, 배포판 상태를 순서대로 확인하는 것이 좋습니다. 오류 코드가 같더라도 시스템 구성에 따라 원인이 다를 수 있습니다.

① WSL 설치 명령어가 인식되지 않는 경우

wsl 명령어를 찾을 수 없거나 설치 옵션을 지원하지 않는다면 Windows 버전과 업데이트 상태를 확인합니다.

지원되지 않는 오래된 Windows 환경에서는 최신 간편 설치 명령을 사용할 수 없을 수 있습니다.

② 오류 0x80370102 발생

이 오류는 WSL2에 필요한 가상화 기능이 활성화되지 않았을 때 발생할 수 있습니다.

작업 관리자에서 CPU 가상화 상태를 확인하고, 필요한 경우 BIOS·UEFI 설정과 Windows의 Virtual Machine Platform 기능을 점검합니다.

③ Virtual Machine Platform 활성화

필요한 경우 관리자 권한 PowerShell에서 다음 명령을 사용할 수 있습니다.

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

명령 실행 후 Windows 재부팅이 필요할 수 있습니다.

④ Windows Subsystem for Linux 기능 활성화

필요한 경우 다음 명령으로 WSL 선택적 기능을 활성화합니다.

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

Windows 버전과 WSL 설치 방식에 따라 이미 활성화되어 있을 수 있습니다.

⑤ WSL 커널 또는 구성 요소 업데이트

관리자 권한 PowerShell에서 다음 명령을 실행합니다.

wsl --update

업데이트가 완료되면 필요에 따라 WSL을 종료하고 다시 실행합니다.

⑥ WSL 상태 확인

다음 명령을 실행합니다.

wsl --status
wsl -l -v

기본 WSL 설정과 설치된 배포판 상태를 확인합니다.

⑦ Ubuntu 실행이 멈추는 경우

먼저 Ubuntu에서 실행 중인 작업을 저장할 수 있는지 확인합니다.

그다음 Windows PowerShell에서 다음 명령으로 WSL을 종료한 뒤 다시 실행할 수 있습니다.

wsl --shutdown
wsl -d Ubuntu

이 명령은 실행 중인 WSL 작업을 중단하므로 데이터 저장 여부를 먼저 확인해야 합니다.

⑧ Ubuntu 사용자 비밀번호를 잊은 경우

배포판이 정상적으로 실행되고 관리자 계정으로 접근할 수 있는 상황에서는 root 사용자로 실행하여 비밀번호를 재설정할 수 있습니다.

Windows PowerShell에서 다음 명령을 실행합니다.

wsl -d Ubuntu -u root

그다음 Ubuntu 셸에서 실제 사용자 이름을 지정하여 비밀번호를 변경합니다.

passwd yourusername

사용자 이름은 실제 계정 이름으로 변경해야 합니다. 조직 관리 환경에서는 계정 복구 정책을 따라야 합니다.

⑨ 인터넷 연결이 되지 않는 경우

Windows 자체의 인터넷 연결부터 확인합니다.

VPN, 프록시, 방화벽, DNS 설정이 WSL 네트워크에 영향을 줄 수 있습니다.

다음 명령으로 DNS 이름 해석과 연결 상태를 점검할 수 있습니다.

getent hosts example.com
curl -I https://example.com

curl이 설치되어 있지 않다면 해당 명령을 사용할 수 없으므로 패키지 설치 여부를 확인해야 합니다.

⑩ localhost 접속이 되지 않는 경우

Linux 내부 서버가 실제로 실행 중인지 확인합니다.

서버가 올바른 포트에서 수신 중인지, Windows와 Linux의 포트가 충돌하지 않는지 점검합니다.

WSL 네트워크 모드와 방화벽 정책에 따라 추가 설정이 필요할 수 있습니다.

⑪ WSL2 메모리 사용량이 많은 경우

WSL2는 실행 중인 작업에 따라 메모리를 사용합니다.

개발 서버, 빌드 도구, Docker 컨테이너 등이 실행 중이라면 메모리 사용량이 증가할 수 있습니다.

필요한 경우 Windows 사용자 홈 디렉터리의 .wslconfig 파일에서 WSL2 가상 머신의 메모리 한도를 설정할 수 있습니다.

[wsl2]
memory=4GB
processors=4

위 설정은 예시이며 컴퓨터의 실제 메모리와 CPU 자원에 맞춰 조정해야 합니다.

설정 변경 후에는 wsl --shutdown으로 WSL을 종료하고 다시 실행해야 적용됩니다.

⑫ WSL 저장 공간이 부족한 경우

Ubuntu 내부에서 다음 명령으로 파일 시스템 사용량을 확인합니다.

df -h
du -sh ~/projects

불필요한 빌드 결과물이나 캐시를 정리할 수 있지만 중요한 프로젝트 파일을 삭제하지 않도록 주의해야 합니다.

⑬ WSL 가상 디스크 크기 주의

WSL2 배포판은 일반적으로 VHDX 형식의 가상 디스크를 사용합니다.

Linux 내부에서 파일을 삭제해도 Windows에 저장된 가상 디스크 파일의 크기가 즉시 줄어들지 않을 수 있습니다.

디스크 축소 작업은 WSL 버전과 파일 시스템 상태에 따라 절차가 다르므로 공식 문서를 확인하고 백업 후 진행해야 합니다.

⑭ WSL 배포판 백업

중요한 프로젝트가 있다면 배포판을 내보내 백업할 수 있습니다.

Windows PowerShell에서 다음 명령을 사용합니다.

wsl --export Ubuntu "D:\Backup\Ubuntu-backup.tar"

대상 폴더는 미리 생성되어 있어야 하며 충분한 저장 공간이 필요합니다.

백업 파일이 정상적으로 생성되었는지도 확인해야 합니다.

⑮ WSL 배포판 삭제 시 주의

다음 명령은 배포판 등록을 해제하는 명령입니다.

wsl --unregister Ubuntu

이 명령을 실행하면 해당 배포판에 저장된 파일과 설정이 삭제될 수 있습니다.

일반적인 실행 오류를 해결하기 위해 처음부터 사용해서는 안 되며, 배포판을 의도적으로 제거하려는 경우에만 백업 후 사용해야 합니다.

⑯ 오류 해결 권장 순서

먼저 오류 메시지와 Windows 버전을 확인하고, 가상화 상태 및 Windows 선택적 기능을 점검합니다.

이후 WSL 업데이트, 재부팅, 배포판 실행 상태 확인을 진행합니다.

설치된 배포판의 파일을 삭제하거나 초기화하는 방법은 마지막 단계에서 신중하게 검토해야 합니다.

문제 증상	우선 확인 사항
wsl 명령어 인식 안 됨	Windows 버전·WSL 설치 상태
0x80370102	CPU 가상화·Virtual Machine Platform
Ubuntu 실행 실패	배포판 상태·WSL 업데이트
WSL1로 표시됨	WSL2 변환 가능 여부
비밀번호 분실	사용자 계정·root 접근 가능 여부
인터넷 연결 실패	DNS·VPN·프록시·방화벽
localhost 접속 실패	서버 실행·포트·네트워크 모드
메모리 과다 사용	실행 프로세스·.wslconfig 설정
디스크 용량 부족	Linux 파일 사용량·VHDX 관리
업데이트 오류	Windows 업데이트·네트워크·관리 정책

7. WSL2 자주 묻는 질문 FAQ

Q1. WSL2를 설치하면 기존 Windows 파일이 삭제되나요?

일반적인 WSL2 설치는 기존 Windows 운영체제를 삭제하거나 포맷하는 작업이 아닙니다. Windows 환경을 유지하면서 Linux 배포판을 추가로 설치하는 방식입니다. 다만 설치 중 시스템 기능이 변경되고 재부팅이 필요할 수 있으므로 중요한 작업 파일은 저장해 두는 것이 좋습니다. 또한 WSL 내부에서 Windows 드라이브에 접근할 수 있으므로 Linux 명령어로 Windows 파일을 수정하거나 삭제할 때는 주의해야 합니다.

Q2. WSL2와 VMware 또는 VirtualBox 중 무엇이 좋나요?

Windows에서 Linux 개발 도구를 사용하려는 목적이라면 WSL2가 간편한 선택이 될 수 있습니다. 반면 독립적인 가상 컴퓨터 구성, 다양한 운영체제 설치, 복잡한 가상 네트워크 실습 등이 필요하다면 VMware나 VirtualBox 같은 가상화 프로그램이 더 적합할 수 있습니다. WSL2도 가상화 기술을 사용하므로 다른 가상화 프로그램과 함께 사용할 때는 버전 및 호환성 조건을 확인해야 합니다.

Q3. WSL2에서 Docker를 사용할 수 있나요?

지원되는 환경에서는 WSL2와 Docker를 함께 사용할 수 있습니다. Docker Desktop의 WSL2 백엔드 및 배포판 통합 기능을 이용하는 방법이 대표적입니다. 다만 Docker 설치 방식과 컨테이너 실행 환경에 따라 필요한 설정이 달라질 수 있습니다. 특히 Docker Desktop을 회사에서 사용하는 경우에는 라이선스 조건을 확인해야 합니다.

Q4. WSL2를 설치하면 컴퓨터가 느려지나요?

WSL2는 실행 중인 Linux 프로세스와 작업량에 따라 CPU, 메모리, 저장 공간을 사용합니다. 아무 작업도 하지 않을 때와 대규모 프로젝트 빌드나 컨테이너를 실행할 때의 자원 사용량은 다릅니다. 성능 문제가 있다면 실행 중인 프로세스를 확인하고, 필요한 경우 WSL을 종료하거나 .wslconfig 파일에서 자원 사용 한도를 조정할 수 있습니다. 다만 지나치게 낮은 자원 한도는 Linux 프로그램의 성능을 떨어뜨릴 수 있습니다.

Q5. WSL2를 삭제했다가 다시 설치하면 Ubuntu 파일이 유지되나요?

WSL 구성 요소를 변경하는 작업과 Linux 배포판 자체를 삭제하는 작업은 구분해야 합니다. 특히 wsl –unregister 명령은 해당 배포판의 데이터와 설정을 삭제할 수 있으므로 주의해야 합니다. Ubuntu를 다시 설치할 계획이라면 먼저 wsl –export 명령으로 배포판을 백업하고, 백업 파일이 정상적으로 생성되었는지 확인하는 것이 좋습니다. 중요한 프로젝트는 Git 원격 저장소나 별도의 백업 위치에도 보관하는 것이 안전합니다.

8. 설치 후 최종 점검 및 관리 체크리스트

WSL2는 한 번 설치하면 다양한 Linux 개발 작업에 활용할 수 있지만 Windows 업데이트, WSL 구성 요소 업데이트, Ubuntu 패키지 관리 등을 구분해서 유지해야 합니다.

특히 Windows에서 실행하는 wsl 명령과 Ubuntu 내부에서 실행하는 apt 명령의 역할이 다르다는 점을 이해하면 관리가 쉬워집니다.

점검 항목	확인 방법
1. Windows 버전	`winver`
2. WSL 설치 상태	`wsl --status`
3. 배포판 목록	`wsl -l -v`
4. WSL 업데이트	`wsl --update`
5. Ubuntu 실행	`wsl -d Ubuntu`
6. Linux 배포판 정보	`cat /etc/os-release`
7. 패키지 목록 업데이트	`sudo apt update`
8. 디스크 사용량	`df -h`
9. 개발 도구 확인	`git --version`, `python3 --version`
10. 배포판 백업	`wsl --export`

WSL2 설치 및 개발 환경 최종 체크리스트

Windows 버전이 WSL2를 지원하는지 확인했습니다.
CPU 가상화 기능이 활성화되어 있는지 확인했습니다.
관리자 권한으로 설치 명령을 실행했습니다.
wsl --install 또는 배포판 지정 설치를 완료했습니다.
필요한 Windows 재부팅을 완료했습니다.
Ubuntu 사용자 계정을 생성했습니다.
Ubuntu 사용자 비밀번호를 설정했습니다.
wsl -l -v에서 WSL 버전 2를 확인했습니다.
Ubuntu 패키지 목록을 업데이트했습니다.
필요한 Ubuntu 패키지를 업그레이드했습니다.
기본 Linux 명령어를 실행해 보았습니다.
Ubuntu 홈 디렉터리에 프로젝트 폴더를 생성했습니다.
Windows 드라이브 접근 경로를 확인했습니다.
Windows 파일 탐색기에서 WSL 파일을 열어 보았습니다.
WSL 가상 디스크 파일을 직접 수정하지 않도록 주의했습니다.
Visual Studio Code를 설치했습니다.
VS Code WSL 확장을 설치했습니다.
VS Code에서 WSL 프로젝트 폴더를 열었습니다.
Ubuntu 내부 Git 설치 상태를 확인했습니다.
Git 사용자 이름과 이메일을 설정했습니다.
Python 설치 상태를 확인했습니다.
Python 가상 환경을 생성했습니다.
필요한 경우 Node.js 개발 환경을 구성했습니다.
필요한 경우 Docker와 WSL2 통합 설정을 확인했습니다.
로컬 웹 서버 접속을 테스트했습니다.
WSL 메모리 사용량을 확인했습니다.
WSL 저장 공간 사용량을 확인했습니다.
중요한 Linux 프로젝트 파일을 백업했습니다.
wsl --unregister의 데이터 삭제 위험을 이해했습니다.
Windows 업데이트와 Ubuntu 패키지 업데이트의 차이를 이해했습니다.

결론: WSL2를 이용하면 Windows에서도 Linux 개발 환경을 구축할 수 있습니다

WSL2는 Windows를 기본 운영체제로 사용하면서 Linux 명령어와 개발 도구를 활용하려는 사용자에게 유용한 기능입니다. 지원되는 Windows 환경에서는 wsl --install 명령으로 설치를 시작할 수 있으며, Ubuntu를 설치하면 별도의 듀얼 부팅 없이 Linux 터미널을 사용할 수 있습니다.

설치 전에는 Windows 버전과 CPU 가상화 상태를 확인하는 것이 중요합니다. 설치 후에는 wsl -l -v 명령으로 배포판의 WSL 버전을 확인하고, Ubuntu 내부에서 패키지 업데이트와 기본 개발 도구 설치를 진행하면 됩니다.

개발 목적으로 사용한다면 Ubuntu 홈 디렉터리에 프로젝트를 저장하고 Visual Studio Code의 WSL 확장 기능을 이용하는 구성이 편리합니다. Git, Python, Node.js, Docker 등 필요한 도구를 추가하면 웹 개발, 자동화 스크립트, 서버 학습 등 다양한 작업을 수행할 수 있습니다.

WSL2 설치 오류가 발생하더라도 처음부터 배포판을 삭제할 필요는 없습니다. Windows 버전, 가상화 기능, WSL 업데이트, 배포판 실행 상태, 네트워크 설정을 차례대로 점검하면 원인을 찾는 데 도움이 됩니다.

권장 설치 순서는 Windows 버전 확인 → CPU 가상화 확인 → 관리자 PowerShell 실행 → wsl –install → 재부팅 → Ubuntu 사용자 생성 → WSL2 버전 확인 → Ubuntu 패키지 업데이트 → VS Code 및 개발 도구 연결 → 프로젝트 백업 설정입니다.

공식 사이트 및 참고 자료

Microsoft Learn. How to install Linux on Windows with WSL. WSL 공식 설치 가이드
Microsoft Learn. Basic commands for WSL. WSL 기본 명령어
Microsoft Learn. Compare WSL versions. WSL1과 WSL2 비교
Microsoft Learn. Troubleshooting Windows Subsystem for Linux. WSL 오류 해결 문서
Microsoft Learn. Advanced settings configuration in WSL. .wslconfig 고급 설정
Microsoft Learn. Working across Windows and Linux file systems. Windows와 Linux 파일 시스템 관리
Visual Studio Code. Developing in WSL. VS Code WSL 개발 환경 안내
Ubuntu Documentation. Ubuntu 공식 문서

※ 이 글은 WSL2 설치 및 Windows 기반 Linux 개발 환경 구축을 위한 일반적인 기술 안내입니다. 실제 설치 과정과 지원 기능은 Windows 버전, WSL 버전, CPU 가상화 지원 여부, 보안 정책 및 Linux 배포판에 따라 달라질 수 있습니다. Windows 선택적 기능과 BIOS·UEFI 설정을 변경할 때는 시스템 구성과 조직 정책을 확인해야 합니다. WSL 배포판 삭제, 가상 디스크 조작, 파일 시스템 변경 등의 작업은 데이터 손실 위험이 있으므로 중요한 프로젝트 파일을 백업한 뒤 진행해야 합니다. 설치 및 문제 해결 과정에서 오류가 발생한다면 Microsoft와 배포판의 최신 공식 문서를 함께 확인하는 것이 좋습니다.