1장: WSL2 설치 및 VS Code 연결¶

WSL이란?¶

WSL(Windows Subsystem for Linux)은 Windows 안에서 Linux를 실행하는 기능입니다. 별도의 가상머신이나 듀얼부팅 없이 Ubuntu 터미널을 그대로 사용할 수 있습니다.

Windows 11
├── Windows 앱 (브라우저, 한글 등)
└── WSL2
    └── Ubuntu (Linux 개발 환경)
        ├── 터미널 (bash, zsh)
        ├── 개발 도구 (git, python, node 등)
        └── VS Code Server (원격 연결)

왜 WSL을 쓰나요? - Linux 기반 개발 도구를 Windows에서 그대로 사용 - 실제 Linux 커널이 돌아가서 호환성이 높음 - VS Code와 자연스럽게 연결됨

1단계: WSL2 활성화¶

PowerShell을 관리자 권한으로 엽니다.

시작 메뉴 → powershell 검색 → 우클릭 → 관리자 권한으로 실행

다음 명령어를 입력합니다:

wsl --install

이 명령어 하나로 WSL2 + Ubuntu가 자동 설치됩니다.

설치가 끝나면 컴퓨터를 재시작합니다.

2단계: Ubuntu 초기 설정¶

재시작 후 자동으로 Ubuntu 터미널이 열립니다. 열리지 않으면:

시작 메뉴 → ubuntu 검색 → 클릭

처음 실행하면 사용자 이름과 비밀번호를 설정합니다:

Enter new UNIX username: (영문 사용자명 입력)
New password: (비밀번호 입력 — 화면에 안 보이는 게 정상)
Retype new password: (비밀번호 다시 입력)

비밀번호는 Linux 시스템의 비밀번호입니다. Windows 비밀번호와 달라도 됩니다.

설정이 완료되면 Ubuntu 터미널이 나타납니다:

username@DESKTOP-XXXXX:~$

3단계: Windows Terminal 설치 (권장)¶

여러 터미널을 탭으로 관리할 수 있는 앱입니다.

Microsoft Store → Windows Terminal 검색 → 설치
실행하면 PowerShell, Ubuntu(WSL)를 탭으로 전환하며 사용 가능

이미 설치되어 있다면 생략하세요.

4단계: Ubuntu 기본 패키지 업데이트¶

Ubuntu 터미널에서 다음 명령어를 실행합니다:

sudo apt update && sudo apt upgrade -y

최신 패키지로 업데이트됩니다. 시간이 조금 걸릴 수 있습니다.

5단계: VS Code에서 WSL 연결¶

VS Code 설치 (안 되어 있는 경우)¶

code.visualstudio.com 에서 다운로드
설치 마법사 따라 진행

WSL 확장 설치¶

VS Code 실행
왼쪽 사이드바에서 확장(Extensions) 아이콘 클릭 (또는 Ctrl+Shift+X)
검색창에 wsl 입력
WSL (Microsoft 제공) → Install 클릭

WSL에 연결¶

방법 A: VS Code에서 연결 1. Ctrl+Shift+P → 명령 팔레트 열기 2. WSL 입력 → WSL: Connect to WSL 선택 3. VS Code 좌측 하단에 WSL: Ubuntu 표시되면 연결 성공

방법 B: 터미널에서 연결 1. Ubuntu 터미널에서 프로젝트 폴더로 이동:

mkdir -p ~/workspace
cd ~/workspace

2. 다음 명령어 실행:

code .

VS Code가 자동으로 열리면서 WSL 환경에 연결됩니다.

연결 확인¶

VS Code 좌측 하단에 다음과 같이 표시되면 정상입니다:

WSL: Ubuntu

이제 VS Code의 터미널(`Ctrl+``)을 열면 Ubuntu 환경이 사용됩니다.

자주 쓰는 명령어¶

동작	명령어
WSL 상태 확인	`wsl --status` (PowerShell)
Ubuntu 실행	`wsl` (PowerShell) 또는 Ubuntu 앱
WSL 종료	`wsl --shutdown` (PowerShell)
VS Code에서 WSL 연결	`code .` (Ubuntu 터미널)

문제 해결¶

`wsl --install`이 안 되는 경우¶

Windows 버전이 오래된 경우입니다. Windows 업데이트 후 다시 시도하세요.

Ubuntu 앱이 안 열리는 경우¶

PowerShell(관리자)에서:

wsl --update
wsl --set-default-version 2

VS Code에서 `code .`이 안 되는 경우¶

VS Code 설치 시 PATH에 추가 옵션이 체크되어 있는지 확인하세요. 또는 VS Code를 다시 설치하세요.