WSL2 및 NVIDIA GPU를 활용해 Windows에서 vLLM을 실행하기

vLLM은 Windows에서 기본적으로 실행되지 않습니다. 공식적으로 지원되는 방법은 Docker와 NVIDIA Container Toolkit이 포함된 WSL2 환경이며, 이를 통해 듀얼 부팅 없이도 GPU 패스스루 기능과 리눅스 기반 추론 환경 전체를 활용할 수 있습니다. 본 가이드에서는 NVIDIA GPU가 장착된 Windows 11 환경에서의 전체 설정 과정을 설명합니다.

Last tested: July 2026. A community PR for native Windows support was submitted but has not been merged into a stable release. Until then, WSL2 + Docker remains the recommended path.

사전 요구 사항

Windows 11 (22H2 or later) with WSL2 enabled
1 or more NVIDIA GPUs with driver version ≥535
WSL2 백엔드가 활성화된 Docker Desktop for Windows
At least 16 GB of system RAM (32 GB recommended for models ≥13B)

단계 1: GPU 지원 기능이 포함된 WSL2 설치하기

관리자 권한으로 PowerShell을 실행한 뒤 WSL2을 설치합니다:

wsl --install

이 과정에서는 기본적으로 Ubuntu가 설치됩니다. 재부팅 후 WSL 커널 버전을 확인해 주세요:

uname -r

GPU 패스스루를 사용하려면 커널 버전이 ≥5.15 이상이어야 합니다. 필요하다면 업데이트해 주세요:

sudo apt update && sudo apt upgrade -y

WSL2 환경 내에서 GPU가 정상적으로 인식되는지 확인해 주세요:

nvidia-smi

올바른 드라이버 버전을 갖춘 GPU가 목록에 표시되어야 합니다. 만약 nvidia-smi에서 장치가 감지되지 않는다면 Windows용 NVIDIA 드라이버를 ≥535 버전으로 업데이트한 뒤 WSL을 재시작해 주세요:

wsl --shutdown

단계 2: NVIDIA Container Toolkit을 포함한 Docker 설치

Windows 환경에 Docker Desktop을 설치합니다.
Docker Desktop 설정 창을 열어 Use the WSL 2 based engine 항목이 체크되어 있는지 확인해 주세요.
Under Resources → WSL Integration, enable your Ubuntu distribution.

WSL2 내에서 NVIDIA Container Toolkit을 설치합니다:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit

설치가 완료되면 Docker를 재시작해 주세요:

sudo service docker restart

단계 3: Docker Compose를 활용해 vLLM 실행하기

Create a docker-compose.yml file:

docker-compose.yml

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --gpu-memory-utilization 0.9
      --max-model-len 8192

컨테이너를 시작하세요:

docker compose up -d

모델이 다운로드되고 로드되는 동안 로그를 지켜보세요:

docker compose logs -f vllm

When you see Uvicorn running on http://0.0.0.0:8000, the server is ready.

단계 4: 정상 작동 여부를 확인하세요

WSL2 내부에서 테스트 요청을 전송하세요:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

예상되는 응답 내용: 모델의 응답이 담긴 choices 배열을 포함하는 JSON 객체입니다.

멀티 GPU 설정 (MCDM)

WSL2은 Microsoft Compute Driver Model(MCDM)을 통해 멀티 GPU 텐서 병렬 처리를 지원합니다. 이 방식은 기존 TCC 모드를 대체하며 NVIDIA 드라이버 버전 ≥535이 필요합니다.

MCDM 모드로 전환하기

Windows 호스트에서 관리자 권한 명령 프롬프트를 열어주세요:

nvidia-smi -g 0 -dm 0

각 GPU마다 이 과정을 반복하되 0 부분을 해당 GPU 인덱스로 대체한 뒤 시스템을 재부팅하세요. 재부팅 후 모든 GPU가 WSL2에 정상적으로 표시되는지 확인하세요:

nvidia-smi

텐서 병렬 처리 기능을 활용해 실행하기

여러 GPU를 사용하도록 docker-compose.yml 명령어를 업데이트하세요:

    command: >
      --model Qwen/Qwen2.5-72B-Instruct
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.9
      --max-model-len 4096

텐서 병렬화는 레이어들을 여러 GPU에 분배하는 방식으로, 단일 노드 내 다중 GPU 환경에서는 파이프라인 병렬화보다 권장됩니다. 이 방식은 디코드 단계에서 더 높은 처리량을 제공합니다.

Windows 호스트에서 연결하기

WSL2 runs in a lightweight VM with its own network. Docker’s port mapping forwards localhost:8000 from the WSL2 VM to the Windows host automatically, so you can reach vLLM from Windows applications:

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"Qwen/Qwen2.5-7B-Instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}"

만약 localhost 포트 전달이 제대로 작동하지 않는다면 WSL2의 IP 주소를 확인한 뒤 직접 사용하시면 됩니다:

hostname -I

그런 다음 Windows 측에서 다음을 수행합니다:

curl http://<WSL2_IP>:8000/v1/chat/completions ...

WSL2의 IP 주소는 재시작할 때마다 변경됩니다. IP 주소를 직접 활용할 경우 매번 재부팅 후 설정을 업데이트해야 합니다. 가능하다면 localhost 포트 전달 방식을 사용하는 것이 좋습니다.

Tokios를 이용해 엔드포인트를 공개하세요

WSL2에서 vLLM을 실행하면 로컬 환경에서 추론이 가능하지만 같은 기기에서만 접근할 수 있습니다. WSL2 내에 vLLM 컨테이너와 함께 Tokios 커넥터를 설치하면 포트 전달이나 방화벽 규칙 없이도 안전한 터널을 통해 어느 기기에서든 모델에 접근할 수 있습니다:

# Inside WSL2, install and pair the connector
curl -fsSL https://install.tokios.com | bash
tokios-connector pair

연결이 완료되면 Models 탭에서 vLLM 배포 정보를 등록하고 API 키를 생성하세요. 그러면 https://api.tokios.com/v1 주소를 통해 어디서든 모델에 접근할 수 있게 됩니다. 전체 절차는 커넥터 설치 페이지를 참고하시기 바랍니다.

문제 해결 방법

GPU not detected in WSL2

현재 사용 중인 NVIDIA 드라이버가 너무 오래되었거나 WSL2 커널이 구버전일 수 있습니다. Windows용 NVIDIA 드라이버를 ≥535 버전으로 업데이트한 뒤 PowerShell에서 wsl --update 명령을 실행하고 wsl --shutdown 명령으로 WSL을 재시작하세요.

CUDA 커널 이미지를 사용할 수 없습니다

Specific vLLM versions (v0.22/v0.23) ship CUDA kernels that don’t match every WSL2 CUDA toolkit version. Pin your Docker image to a known-good tag, for example vllm/vllm-openai:v0.21.0, instead of latest.

다중 GPU 환경에서 메모리 부족 현상 발생

vLLM은 Ollama보다 CUDA 그래프 처리를 위해 더 많은 VRAM를 할당합니다. 만약 32B 모델이 2x RTX 3090에서 메모리 부족 오류를 일으킨다면 --gpu-memory-utilization 값을 0.85 수준으로 낮추거나 --max-model-len 크기를 줄여보시기 바랍니다.

Docker 컨테이너가 즉시 종료됩니다

먼저 Docker Desktop의 WSL2 통합 기능이 사용 중인 배포판에 대해 활성화되어 있는지 확인하세요. docker compose logs vllm 명령을 실행하면 종료 원인을 확인할 수 있으며, 대개 GPU 드라이버 누락이나 잘못된 모델 경로가 원인입니다.

MCDM 기능이 활성화되지 않았습니다

If nvidia-smi inside WSL2 only shows 1 GPU on a multi-GPU system, MCDM may not be active. Run nvidia-smi -g <GPU_ID> -dm 0 on the Windows host for each GPU, then reboot.

Windows 네이티브 환경 지원 현황

SystemPanic이 개발한 커뮤니티 포크 버전은 WSL2이나 Docker 없이도 vLLM을 Windows에서 사용할 수 있게 해줍니다. 이 기능은 2025 초기에 제안되었으나 아직 안정적인 릴리스에 포함되지 않았습니다. 진행 상황은 vLLM GitHub 저장소에서 확인하실 수 있습니다. 안정적인 릴리스 버전에서 네이티브 지원이 제공되기 전까지는 WSL2와 Docker를 조합하여 사용하는 것이 Windows 환경에서의 배포 방안입니다.

다음 단계

vLLM 원격 접속 방법

Tokios를 활용하면 포트 포워딩 없이도 어떤 기기에서든 자신의 vLLM 서버에 접속할 수 있습니다.

모델 적합성 확인

어떤 모델이 사용 중인 GPU의 VRAM 용량에 적합하며 어느 정도의 처리 속도가 기대되는지 알아보세요.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

WSL2 및 NVIDIA GPU를 활용해 Windows에서 vLLM을 실행하기

사전 요구 사항

단계 1: GPU 지원 기능이 포함된 WSL2 설치하기

단계 2: NVIDIA Container Toolkit을 포함한 Docker 설치

단계 3: Docker Compose를 활용해 vLLM 실행하기

단계 4: 정상 작동 여부를 확인하세요

멀티 GPU 설정 (MCDM)

MCDM 모드로 전환하기

텐서 병렬 처리 기능을 활용해 실행하기

Windows 호스트에서 연결하기

Tokios를 이용해 엔드포인트를 공개하세요

문제 해결 방법

Windows 네이티브 환경 지원 현황

다음 단계

vLLM 원격 접속 방법

모델 적합성 확인

​사전 요구 사항

​단계 1: GPU 지원 기능이 포함된 WSL2 설치하기

​단계 2: NVIDIA Container Toolkit을 포함한 Docker 설치

​단계 3: Docker Compose를 활용해 vLLM 실행하기

​단계 4: 정상 작동 여부를 확인하세요

​멀티 GPU 설정 (MCDM)

​MCDM 모드로 전환하기

​텐서 병렬 처리 기능을 활용해 실행하기

​Windows 호스트에서 연결하기

​Tokios를 이용해 엔드포인트를 공개하세요

​문제 해결 방법

​Windows 네이티브 환경 지원 현황

​다음 단계

vLLM 원격 접속 방법

모델 적합성 확인

사전 요구 사항

단계 1: GPU 지원 기능이 포함된 WSL2 설치하기

단계 2: NVIDIA Container Toolkit을 포함한 Docker 설치

단계 3: Docker Compose를 활용해 vLLM 실행하기

단계 4: 정상 작동 여부를 확인하세요

멀티 GPU 설정 (MCDM)

MCDM 모드로 전환하기

텐서 병렬 처리 기능을 활용해 실행하기

Windows 호스트에서 연결하기

Tokios를 이용해 엔드포인트를 공개하세요

문제 해결 방법

Windows 네이티브 환경 지원 현황

다음 단계