> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# WSL (Windows Subsystem for Linux) 설치 가이드

## WSL이란?

WSL(Windows Subsystem for Linux)은 Windows 위에서 Linux 환경을 바로 실행할 수 있게 해주는 기능입니다. 별도의 가상 머신이나 듀얼 부팅 없이도 Windows 안에서 Linux 명령어와 도구를 사용할 수 있습니다.

<Note>
  많은 개발 도구와 서버 환경이 Linux 기반입니다. WSL을 사용하면 Windows에서 Linux 전용 도구들을 사용할 수 있으며, Docker(Rancher Desktop 등)를 Windows에서 사용하려면 WSL2가 반드시 필요합니다.
</Note>

## 사전 요구사항

| 항목   | 요구사항                                |
| ---- | ----------------------------------- |
| 운영체제 | Windows 10 버전 2004 이상 또는 Windows 11 |
| 권한   | 컴퓨터 관리자 권한 필수                       |
| 인터넷  | 설치 파일 다운로드를 위한 인터넷 연결               |

<Warning>
  WSL 설치에는 **관리자 권한**이 반드시 필요합니다. 일반 사용자 권한으로는 설치할 수 없습니다.
</Warning>

## 설치

<Steps>
  <Step title="관리자 권한으로 PowerShell 열기">
    먼저 PowerShell을 **관리자 권한**으로 열어야 합니다. 방법은 다음과 같습니다:

    1. Windows 키를 누르거나 화면 하단의 검색 아이콘을 클릭합니다
    2. **"PowerShell"** 을 입력합니다
    3. 검색 결과에서 **"Windows PowerShell"** 을 찾습니다
    4. **"관리자 권한으로 실행"** 을 클릭합니다
    5. "이 앱이 디바이스를 변경할 수 있도록 허용하시겠어요?" 라는 팝업이 나타나면 **예**를 클릭합니다

    <Note>
      PowerShell 창의 제목 표시줄에 **"관리자: Windows PowerShell"** 이라고 표시되어야 합니다. "관리자"라는 글자가 없으면 일반 권한으로 열린 것이므로, 닫고 다시 관리자 권한으로 열어야 합니다.
    </Note>

    관리자 PowerShell이 열리면 다음 명령어를 입력하고 Enter 키를 누릅니다:

    ```powershell theme={null}
    wsl --install
    ```

    <img src="https://mintcdn.com/ddok/vpYxTFFktlX5a4TM/images/environment-setup/windows/wsl/01-wsl-install-admin-ps.png?fit=max&auto=format&n=vpYxTFFktlX5a4TM&q=85&s=e6b631892042fccc91803bf674eaef04" alt="관리자 PowerShell에서 wsl --install 명령어 실행" width="979" height="512" data-path="images/environment-setup/windows/wsl/01-wsl-install-admin-ps.png" />

    이 명령어로 WSL에 필요한 모든 구성 요소가 자동으로 설치됩니다.
  </Step>

  <Step title="설치 완료 확인 및 재시작">
    설치가 진행되면서 "VirtualMachinePlatform" 등 필요한 Windows 기능이 활성화됩니다. 진행률이 100%에 도달하면 설치가 완료됩니다.

    <img src="https://mintcdn.com/ddok/vpYxTFFktlX5a4TM/images/environment-setup/windows/wsl/02-wsl-install-complete.png?fit=max&auto=format&n=vpYxTFFktlX5a4TM&q=85&s=36bfc313f58faf5dfa083e2432cec8a6" alt="WSL 설치 완료 - VirtualMachinePlatform 100% 설치, 재시작 필요" width="979" height="512" data-path="images/environment-setup/windows/wsl/02-wsl-install-complete.png" />

    화면에 **"요청한 작업이 잘 실행되었습니다. 시스템을 다시 시작하면 변경 사항이 적용됩니다."** 라는 메시지가 표시됩니다.

    <Warning>
      **반드시 컴퓨터를 재시작해야 합니다.** 재시작하지 않으면 WSL이 정상적으로 동작하지 않습니다. 진행 중인 작업을 모두 저장한 후 컴퓨터를 재시작합니다.
    </Warning>

    재시작하려면 시작 메뉴 > 전원 > 다시 시작을 클릭하거나, PowerShell에서 다음 명령어를 입력합니다:

    ```powershell theme={null}
    Restart-Computer
    ```
  </Step>

  <Step title="설치 상태 확인하기">
    컴퓨터가 재시작된 후, 다시 PowerShell을 열고 (이번에는 관리자 권한이 아니어도 됩니다) 다음 명령어를 입력하여 WSL이 정상적으로 설치되었는지 확인합니다:

    ```powershell theme={null}
    wsl -l -v
    ```

    <img src="https://mintcdn.com/ddok/vpYxTFFktlX5a4TM/images/environment-setup/windows/wsl/03-wsl-no-distro.png?fit=max&auto=format&n=vpYxTFFktlX5a4TM&q=85&s=2383680300a1db288eff9e21e07d0ed8" alt="wsl -l -v 실행 결과 - 설치된 배포가 없음" width="979" height="512" data-path="images/environment-setup/windows/wsl/03-wsl-no-distro.png" />

    아직 Linux 배포판을 설치하지 않았기 때문에 **"Linux용 Windows 하위 시스템 설치된 배포가 없습니다"** 라는 메시지가 표시됩니다. WSL 자체는 정상적으로 설치되었으며, Linux 배포판(예: Ubuntu)은 별도로 설치해야 합니다.

    <Note>
      Rancher Desktop과 같은 Docker 관련 프로그램을 설치하면 자체 WSL 배포판이 자동으로 등록되므로, 별도로 Ubuntu 등을 설치하지 않아도 괜찮습니다.
    </Note>
  </Step>
</Steps>

## Linux 배포판 설치 (선택사항)

WSL에서 직접 Linux 환경을 사용하고 싶다면, Ubuntu 등의 Linux 배포판을 추가로 설치할 수 있습니다.

### 방법 1: 명령어로 설치

```powershell theme={null}
wsl --install -d Ubuntu
```

이 명령어를 실행하면 Ubuntu가 자동으로 다운로드되고 설치됩니다. 설치 완료 후 사용자 이름과 비밀번호를 설정하는 화면이 나타납니다.

### 방법 2: Microsoft Store에서 설치

1. Microsoft Store를 엽니다
2. "Ubuntu" 등 원하는 Linux 배포판을 검색합니다
3. **받기** 또는 **설치** 버튼을 클릭합니다

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

어떤 배포판을 설치할 수 있는지 보려면 다음 명령어를 실행합니다:

```powershell theme={null}
wsl --list --online
```

## 문제 해결

* **"가상화 기술이 활성화되지 않았습니다" 오류**: BIOS에서 가상화(VT-x 또는 AMD-V) 기능을 활성화해야 합니다. 컴퓨터 제조사별로 BIOS 진입 방법이 다르니, 해당 제조사의 안내를 참고합니다.
* **`wsl --install`이 동작하지 않는 경우**: Windows 버전이 너무 오래된 것일 수 있습니다. Windows 업데이트를 먼저 실행합니다.
* **WSL 관련 오류 발생 시**: `wsl --update` 명령어를 실행하여 WSL을 최신 버전으로 업데이트합니다.

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Git for Windows" icon="arrow-right" href="/setup/windows/git">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>