WSL2 설치와 Ubuntu 초기 세팅 가이드

이 글에서 다루는 내용

Windows에서 WSL2를 활성화하고 Ubuntu 배포판을 설치한 뒤, 실제 개발을 바로 시작할 수 있는 상태까지 만드는 초기 세팅 과정을 정리합니다. 네이티브 Linux 없이 윈도우 위에서 Docker, Claude Code, Python 개발을 안정적으로 돌리려면 WSL2가 가장 현실적인 선택지입니다. VirtualBox나 VMware 같은 풀 가상화에 비해 부팅이 빠르고, 파일 시스템과 네트워크가 Windows와 자연스럽게 연결되어 IDE 통합에서 마찰이 적습니다.

WSL1과 WSL2는 이름은 비슷하지만 내부 구조가 완전히 다릅니다. WSL1은 Linux 시스템 콜을 윈도우 커널이 흉내 내는 방식이라 호환성에 한계가 있고, WSL2는 경량 Hyper-V 가상 머신 위에서 진짜 Linux 커널을 돌립니다. Docker가 WSL2를 요구하는 이유도 여기에 있습니다. 신규 프로젝트라면 망설일 이유 없이 WSL2를 기본값으로 잡습니다.

1. WSL2 활성화

1-1. 한 줄 설치 명령

Windows 11 이상에서는 관리자 PowerShell에서 한 줄이면 끝납니다. Windows 10의 경우 21H2 이상 빌드여야 같은 명령이 동작합니다.

wsl --install

이 명령은 WSL 구성 요소를 켜고 기본 배포판인 Ubuntu를 함께 설치합니다. 가상화 기능과 Hyper-V 플랫폼 활성화가 함께 일어나기 때문에, 실행 후 재부팅이 필요합니다. 노트북이라면 전원에 연결한 상태로 재부팅하는 편이 안전합니다.

1-2. 버전 확인

재부팅 후 PowerShell에서 버전을 확인합니다. 두 명령으로 WSL 자체와 설치된 배포판이 어느 버전으로 동작하는지 모두 알 수 있습니다.

wsl --status
wsl -l -v

예상 출력 보기

NAME        STATE           VERSION
* Ubuntu    Running         2

VERSION이 2가 아니라면 강제로 업그레이드합니다. 동시에 신규 배포판이 자동으로 2가 되도록 기본값도 잡아둡니다.

wsl --set-version Ubuntu 2
wsl --set-default-version 2

⚠️ WSL1과 WSL2는 파일 I/O 성능 차이가 상당합니다. node_modules처럼 작은 파일이 수만 개 생성되는 워크로드에서는 WSL1이 체감상 수 배 느려집니다. 신규 프로젝트는 무조건 WSL2를 사용합니다.

1-3. 다른 배포판 선택

기본 Ubuntu 외에 Debian, openSUSE, Fedora 등도 마이크로소프트 스토어에서 받을 수 있습니다. 다만 한국어 자료와 패키지 생태계가 가장 풍부한 쪽은 여전히 Ubuntu LTS입니다. 처음 도입한다면 Ubuntu 22.04 또는 24.04 LTS를 권장합니다. 설치된 배포판 목록은 wsl --list --online으로 확인할 수 있습니다.

2. Ubuntu 최초 로그인과 사용자 설정

2-1. 사용자 계정 생성

시작 메뉴에서 "Ubuntu"를 실행하면 사용자 이름과 비밀번호를 묻습니다. 윈도우 계정과 별개이므로 원하는 이름으로 만들어도 됩니다. 영문 소문자에 공백 없는 짧은 이름이 가장 다루기 편하고, 이후 셸 프롬프트나 SSH 사용자명에 그대로 노출되니 보안상으로도 너무 식별 가능한 본명은 피하는 편이 좋습니다. 입력한 사용자는 자동으로 sudo 그룹에 들어갑니다.

2-2. 패키지 업데이트

처음 들어가면 패키지 목록이 오래된 상태입니다. 먼저 최신화합니다. apt update는 패키지 인덱스만 갱신하고, 실제 업그레이드는 apt upgrade가 수행합니다.

sudo apt update && sudo apt upgrade -y

업그레이드는 첫 실행이면 수백 MB 단위로 받아오기 때문에 시간이 좀 걸립니다. 진행 중 커피 한 잔 타오기 좋은 타이밍입니다. 정기적으로(주 1회 정도) 같은 명령을 돌려두면 보안 패치를 놓치지 않습니다.

3. 필수 도구 설치

3-1. 개발 기본 패키지

대부분의 개발 환경에서 필수적으로 쓰이는 도구들을 한 번에 설치합니다. 이후에 Python·Node·Docker 등을 설치할 때 이 패키지들이 의존성으로 자주 호출되기 때문에, 처음에 깔아두면 설치 단계마다 막히는 일이 줄어듭니다.

sudo apt install -y build-essential curl wget git unzip \
  ca-certificates software-properties-common

각 패키지의 역할은 아래와 같습니다.

패키지	용도
build-essential	gcc, make 등 컴파일 도구
curl / wget	네트워크 다운로드
git	버전 관리
unzip	압축 해제
ca-certificates	SSL 인증서
software-properties-common	PPA 저장소 추가용

3-2. 한글 로케일 설정

로케일이 C나 en_US이면 한글 파일명이 깨지거나 Python의 print 출력이 인코딩 에러를 내기도 합니다. 한국어 사용 환경이라면 처음부터 ko_KR.UTF-8로 맞추는 편이 안전합니다.

sudo apt install -y language-pack-ko
sudo locale-gen ko_KR.UTF-8
sudo update-locale LANG=ko_KR.UTF-8

적용 후 터미널을 재시작하고 확인합니다.

locale

3-3. Windows Terminal 사용 권장

WSL 자체와는 별개로, 터미널 앱은 Windows Terminal(스토어 기본 설치)을 쓰는 편이 가장 편합니다. 탭 분할, 한글 폰트 자유도, 색상 테마, GPU 가속 렌더링 등 기본 cmd/PowerShell 창보다 모든 면에서 낫습니다. 시작 메뉴에서 "Terminal"을 실행한 뒤 위쪽 ▼ 메뉴에서 Ubuntu 프로필을 기본값으로 지정해두면, 새 탭을 열 때마다 WSL이 바로 뜹니다.

4. 셸 환경 정리

4-1. zsh + oh-my-zsh

기본 bash도 나쁘지 않지만, 자동완성과 Git 상태 표시 면에서는 zsh가 편합니다. 특히 oh-my-zsh의 git 플러그인이 브랜치명과 변경 상태를 프롬프트에 자동 표시해 줘서, 작업 도중 잘못된 브랜치에 커밋하는 실수를 줄여줍니다.

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

설치 중간에 기본 셸 변경 여부를 물어봅니다. Y를 입력합니다. 변경 후에는 새 터미널을 열어야 적용됩니다.

4-2. 가볍게 추천하는 플러그인

~/.zshrc 파일의 plugins 라인을 다음과 같이 수정합니다.

plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

플러그인을 설치합니다.

git clone https://github.com/zsh-users/zsh-autosuggestions \
  ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
source ~/.zshrc

💡 zsh-autosuggestions는 과거 입력을 기반으로 회색 유령 텍스트를 보여줍니다. Tab 없이 → 키로 바로 완성할 수 있어 생산성이 눈에 띄게 올라갑니다. zsh-syntax-highlighting은 잘못된 명령을 빨간색으로 즉시 표시해, 엔터를 치기 전에 오타를 잡아냅니다.

5. 개발 디렉터리 구조와 파일 시스템 이해

WSL2를 다룰 때 가장 자주 혼동되는 지점이 파일 시스템 위치입니다. Windows와 WSL은 서로의 파일을 마운트로 들여다볼 수 있지만, 어느 쪽에 두느냐에 따라 성능 차이가 큽니다.

WSL2 파일 시스템 — 빠른 쪽과 느린 쪽 Windows 측 (NTFS) C:\Users\...\Documents WSL에서 /mnt/c/로 보임 · 느림 WSL2 측 (ext4 가상 디스크) ~/dev/my-project Linux 네이티브 I/O · 빠름 프로젝트 폴더는 WSL 홈(~) 안에 두는 것을 원칙으로 합니다.

Windows 파일 시스템(/mnt/c/) 아래에서 작업하면 9P 프로토콜을 거치기 때문에 파일 접근이 매우 느립니다. WSL 내부 홈(~/)에 프로젝트 폴더를 두는 것이 원칙입니다. 작업용·개인용·실험용 폴더를 미리 분리해두면 IDE에서 워크스페이스를 열 때 길을 잃지 않습니다.

mkdir -p ~/dev/work ~/dev/personal ~/dev/sandbox

반대로 WSL에서 Windows 파일에 접근해야 한다면 /mnt/c/Users/<이름>/ 경로로 들어갈 수 있습니다. 다운로드 받은 파일을 옮기는 정도의 가벼운 작업에 쓰고, 빌드 산출물이 자주 쌓이는 작업은 WSL 쪽 폴더에서 처리합니다. VS Code로 WSL 폴더를 여는 방법은 7번 VS Code 세팅 편에서 자세히 다룹니다.

6. 성능 튜닝과 메모리 제한

WSL2는 기본값으로 Windows 메모리의 절반까지 가져갈 수 있습니다. 8GB나 16GB 노트북에서 IDE·브라우저까지 함께 띄우면 Windows가 답답해지는 경우가 있는데, .wslconfig 파일로 한도를 명시적으로 잡아두면 안정적입니다. Windows 사용자 폴더(C:\Users\<이름>\.wslconfig)에 만듭니다.

[wsl2]
memory=6GB
processors=4
swap=2GB

저장 후 PowerShell에서 wsl --shutdown을 실행하면 다음 기동부터 적용됩니다. 메모리 값은 실 장착량의 60% 정도가 적당하고, swap을 1~2GB 두면 단발성 컴파일 피크에서 OOM(Out Of Memory)을 피할 수 있습니다.

트러블슈팅

문제 1: `wsl --install` 실행 시 "기능이 없다"는 오류

Windows 기능 중 "Virtual Machine Platform"과 "Linux용 Windows 하위 시스템"이 꺼져 있을 수 있습니다. BIOS에서 가상화(VT-x/AMD-V) 자체가 꺼져 있는 경우도 있으니, BIOS 설정도 함께 확인합니다.

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

실행 후 재부팅하고 다시 시도합니다.

문제 2: WSL 내부에서 인터넷이 되지 않음

VPN이나 일부 보안 솔루션(특히 사내망 클라이언트)이 WSL의 네트워크 스택을 막는 경우가 있습니다. 아래 파일을 만들고 wsl --shutdown 후 재시작합니다.

# /etc/wsl.conf
[network]
generateResolvConf = false

그리고 /etc/resolv.conf를 수동으로 작성합니다.

nameserver 8.8.8.8

문제 3: 디스크 용량이 계속 늘어남

WSL의 가상 디스크(VHDX)는 한 번 늘어나면 자동으로 줄어들지 않습니다. Linux 안에서 파일을 지워도 호스트 디스크에서는 그대로 점유 중인 상태가 됩니다. 주기적으로 압축해줍니다.

wsl --shutdown
diskpart
# diskpart 안에서
select vdisk file="C:\Users\<사용자>\AppData\Local\Packages\...\ext4.vhdx"
compact vdisk

문제 4: Docker Desktop과 WSL이 충돌

Docker Desktop을 별도로 설치하면 자체 WSL 배포판(docker-desktop, docker-desktop-data)이 추가됩니다. 이 자체는 정상이지만, Ubuntu 안에서 docker 명령이 안 잡힌다면 Docker Desktop 설정의 "Use WSL2 based engine"과 "Enable integration with my default WSL distro"를 켰는지 확인합니다.

마무리

WSL2는 이제 "윈도우 위 리눅스"를 넘어, 대부분의 개발자들이 기본값으로 쓰는 환경입니다. 여기에 Docker, Python, Claude Code를 얹으면 데스크톱 한 대로도 충분히 풀스택 개발이 가능합니다. 처음 세팅 후에는 .wslconfig로 메모리 한도를 미리 잡아두고, 디스크 압축을 분기에 한 번씩 돌려주는 습관만 들여도 장기적으로 쾌적하게 쓸 수 있습니다. 다음 글에서는 VS Code를 WSL과 연동해 실제 편집 환경을 완성합니다.

공식 문서: https://learn.microsoft.com/ko-kr/windows/wsl/
다음 글: VS Code 개발 환경 최적화 세팅

같은 시리즈의 다른 글

Git 초보 탈출 — 실무에서 쓰는 명령어 정리

'개발환경 & 도구' 카테고리의 다른 글

Docker 설치부터 컨테이너 실행까지 (1)	2026.04.26
Git 초보 탈출 — 실무에서 쓰는 명령어 정리 (1)	2026.04.22
VS Code 개발 환경 최적화 세팅 (2)	2026.04.19
Python 가상환경 Anaconda 완벽 정리 (1)	2026.04.19
Python 가상환경(venv) 완벽 정리 (0)	2026.04.19