WSL2 완벽 가이드: Windows에서 Ubuntu 개발 환경 구축하기

Windows에서 리눅스 개발 환경이 필요하지만 듀얼부팅이나 무거운 가상머신은 부담스럽다면, WSL2(Windows Subsystem for Linux 2)가 해답입니다. 실제 리눅스 커널 기반으로 Docker 컨테이너, 머신러닝 패키지 설치 등에서 체감 성능이 우수하며, Windows Terminal과 VSCode Remote 연동으로 네이티브 리눅스 못지않은 개발 워크플로우를 구축할 수 있습니다. 이 글에서는 WSL2 설치부터 Ubuntu 초기 세팅, 터미널 커스터마이징, 권한 문제 해결까지 실전 트러블슈팅 중심으로 정리합니다.

WSL2완벽가이드Windows에서Ubuntu개발환경구축하기

WSL2 선택 이유와 사전 확인

WSL은 Windows에서 가상머신 없이 리눅스 환경을 제공하는 기능이며, WSL1과 WSL2로 나뉩니다.

WSL1: Windows 시스템 콜을 번역하는 방식으로 동작하며, 파일 시스템 성능이 상대적으로 낮습니다.
WSL2: 실제 리눅스 커널을 경량 가상화로 실행하여 파일 시스템 성능, 호환성, 컨테이너 지원이 우수합니다. Docker Desktop, TensorFlow, PyTorch 등 컨테이너 및 머신러닝 워크로드에 최적화되어 있습니다.

맥 노트북에서 발열 문제로 Windows 환경으로 전환하며 WSL2를 도입한 결과, 게임/메신저는 Windows에서, 코딩/머신러닝 작업은 리눅스 환경에서 병행할 수 있어 생산성이 크게 향상되었습니다.

사전 확인 사항:

Windows 10 버전 2004 이상 또는 Windows 11 (PowerShell에서 winver 명령으로 확인)
BIOS에서 가상화 기술(Intel VT-x / AMD-V) 활성화 여부

WSL2 설치 및 Ubuntu 초기 세팅

1단계: Windows 기능 활성화

WSL2를 사용하려면 두 가지 Windows 기능을 활성화해야 합니다.

Windows 키 + R → appwiz.cpl 입력 → 좌측 'Windows 기능 켜기/끄기' 클릭
다음 두 항목을 체크:
- Linux용 Windows 하위 시스템
- 가상 머신 플랫폼
확인 후 재부팅

또는 PowerShell(관리자 권한)에서 다음 명령을 실행:

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

2단계: WSL2 설치 및 기본 버전 설정

PowerShell(관리자)에서 다음 명령을 순서대로 실행합니다.

wsl --install
wsl.exe --update
wsl --set-default-version 2

특정 배포판(Ubuntu 22.04 LTS 권장)을 설치하려면:

wsl --install -d Ubuntu-22.04

또는 Microsoft Store에서 'Ubuntu' 검색 후 원하는 LTS 버전을 설치할 수 있습니다.

3단계: Ubuntu 초기 실행 및 사용자 설정

설치 후 Ubuntu를 실행하면 사용자 이름(username)과 비밀번호(password)를 설정하라는 프롬프트가 나타납니다.

영문 소문자 사용자명 권장: 한글 사용자명은 권한 문제 및 인코딩 이슈를 유발할 수 있습니다.
sudo 비밀번호를 잊지 마세요: 관리자 권한 작업 시 반복적으로 요구됩니다.

초기 업데이트 및 업그레이드:

lsb_release -a
sudo apt update && sudo apt upgrade -y

4단계: 설치 확인 및 주요 명령

설치된 배포판 및 WSL 버전 확인:

wsl -l -v

출력 예시에서 VERSION 열이 2로 표시되면 WSL2가 정상 적용된 것입니다.

자주 사용하는 WSL 관리 명령:

wsl --shutdown: 모든 WSL 인스턴스 종료
wsl --terminate Ubuntu-22.04: 특정 배포판 종료
wsl -d Ubuntu-22.04: 특정 배포판으로 진입

주의: WSL 내부(Ubuntu 터미널)에서 wsl 명령을 실행하면 오류가 발생합니다. 종료·관리 명령은 Windows의 cmd 또는 PowerShell에서 실행하십시오.

파일 시스템 구조와 권한 문제 해결

파일 저장 권장 위치

Windows 드라이브 접근: /mnt/c, /mnt/d 등으로 접근 가능
권장 작업 위치: /home/사용자이름 (WSL 내부 파일 시스템)
금지 사항: 루트(/, /bin, /usr 등) 또는 시스템 디렉토리에서 임의 수정

홈 디렉토리에 작업 폴더 생성:

mkdir ~/work
cd ~/work

권한 문제 (Operation not permitted) 해결

Windows 파일 시스템(/mnt/c)에서 작업 시 권한 오류가 발생할 수 있습니다. 이는 NTFS와 리눅스 권한 체계 차이 때문입니다.

해결 방법 1: WSL 내부 파일 시스템 사용 (권장)

가능하면 ~/(홈 디렉토리)에서 작업하십시오. 파일 시스템 성능도 이쪽이 훨씬 빠릅니다.

해결 방법 2: 메타데이터 옵션으로 재마운트

sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata

이후 wsl --shutdown으로 종료 후 재접속하면 권한 문제가 해결됩니다.

Windows와 WSL 간 파일 이동

WSL 내부에서 현재 경로를 Windows 탐색기로 열기:

explorer.exe .

Windows에서 WSL 파일 시스템 접근: \\wsl$\Ubuntu-22.04\home\사용자이름 경로로 네트워크 드라이브처럼 접근 가능합니다.

개발 환경 최적화: Windows Terminal과 VSCode 연동

Windows Terminal 설치 및 커스터마이징

PowerShell, cmd, WSL을 통합 관리하려면 Windows Terminal을 설치하십시오.

Microsoft Store에서 'Terminal' 검색 후 설치
또는 Chocolatey: choco install microsoft-windows-terminal

한글 인코딩 문제 해결:

한글 사용자명이나 경로에서 깨짐 현상이 발생하면 PowerShell 프로파일에 다음 명령을 추가:

notepad $PROFILE

메모장에 다음 줄을 추가 후 저장:

[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8

터미널 꾸미기 (선택사항):

설정(Settings) → 모양(Appearance)에서 배경 이미지, 투명도, 아크릴 재질 적용
꿀팁: 투명도를 20~30% 정도 주면 여러 창 중 포커스된 터미널을 한눈에 구별할 수 있습니다. 배경은 차분한 단색 또는 심플한 이미지를 권장합니다.

VSCode Remote Development 연동

WSL2 환경에서 네이티브 리눅스처럼 개발하려면 VSCode Remote Development 확장을 설치하십시오.

VSCode 확장 마켓플레이스에서 'Remote Development' 검색 후 설치
Ctrl+Shift+P → WSL: New WSL Window 또는 WSL: Connect to WSL 실행
WSL 내부에서 현재 경로로 VSCode 열기: code .

작업 흐름:

Windows에서 VSCode를 실행하면 좌측 하단에 원격 연결 상태가 표시됩니다.
WSL 환경에 연결되면 터미널, 확장, 파일 시스템 모두 리눅스 기준으로 동작합니다.
원격 연결을 끊으려면 좌측 하단 상태창에서 '원격 연결 닫기' 또는 새 창 열기를 선택하십시오.

리소스 제한 설정 (.wslconfig)

WSL2는 기본적으로 시스템 메모리의 50%까지 사용할 수 있습니다. 메모리 과다 사용 시 .wslconfig 파일로 제한하십시오.

Windows 사용자 폴더에 .wslconfig 파일 생성:

C:\Users\[사용자명]\.wslconfig

내용 예시:

[wsl2]
memory=4GB
processors=2

설정 후 wsl --shutdown으로 재시작하면 적용됩니다.

터미널 커스터마이징: oh-my-zsh와 Powerlevel10k (선택사항)

가독성과 생산성을 높이려면 oh-my-zsh와 Powerlevel10k 테마를 설치하십시오.

설치 순서

zsh 및 git 설치:

sudo apt update
sudo apt install git zsh -y

oh-my-zsh 설치:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Powerlevel10k 테마 설치:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

~/.zshrc 파일 편집:
```
nano ~/.zshrc
    
```
ZSH_THEME="powerlevel10k/powerlevel10k"로 변경 후 저장
터미널 재시작 후 Powerlevel10k 설정 마법사 실행

폰트 설치 (Windows)

Powerlevel10k는 Nerd Font가 필요합니다. 폰트가 없으면 아이콘이 깨져 보입니다.

Windows에서 PowerShell(관리자)로 폰트 저장소 클론:

git clone https://github.com/powerline/fonts.git
cd fonts
.\install.ps1

또는 MesloLGS NF, DejaVu Sans Mono for Powerline 등을 수동 다운로드 후 설치
Windows Terminal 설정 → 프로필 → Ubuntu → 모양 → 글꼴에서 설치한 폰트 선택

유용한 플러그인 추가

git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
sudo apt install autojump

~/.zshrc에서 plugins=(git zsh-autosuggestions zsh-syntax-highlighting autojump)로 수정 후 source ~/.zshrc 실행

실전 트러블슈팅 체크리스트

WSL 버전 확인: wsl -l -v에서 VERSION이 2인지 확인. 1이면 wsl --set-version Ubuntu-22.04 2로 변환
네트워크 연결 안 됨: wsl --shutdown 후 재시작. Windows 방화벽에서 WSL 예외 추가
파일 권한 오류: /mnt/c 대신 ~/에서 작업하거나 -o metadata 옵션으로 재마운트
메모리 과다 사용: .wslconfig로 메모리 제한 설정
VSCode 연결 실패: Remote Development 확장 재설치, WSL 재시작

마무리

WSL2는 Windows에서 리눅스 개발 환경을 구축하는 가장 효율적인 방법입니다. 듀얼부팅 없이 Docker, Kubernetes, 머신러닝 프레임워크를 네이티브 성능으로 실행할 수 있으며, VSCode Remote와 Windows Terminal 조합으로 생산성을 극대화할 수 있습니다.

지금 당장 실행할 Action Item:

PowerShell(관리자)에서 wsl --install -d Ubuntu-22.04 실행
VSCode에 Remote Development 확장 설치
~/work 폴더 생성 후 첫 프로젝트를 WSL 환경에서 시작하십시오

# 함께 보면 좋은 글

Phantom-Shell

이 블로그 검색

Crontab 파이썬 스크립트 실행 안될 때 환경변수 PATH 문제 해결 완벽 정리