[Bug Fix] Allow pinned memory for WSL2 (#41496)

Signed-off-by: Jimmy Lee <hirejimmylee@gmail.com>
This commit is contained in:
Jimmy Lee
2026-06-16 05:56:26 +00:00
committed by GitHub
parent 9096659edb
commit 8bf374955f
4 changed files with 431 additions and 3 deletions
+59 -1
View File
@@ -7,6 +7,7 @@ pynvml. However, it should not initialize cuda context.
from __future__ import annotations
import os
import platform
from collections.abc import Callable
from datetime import timedelta
from functools import cache, lru_cache, wraps
@@ -26,7 +27,7 @@ from vllm.utils.import_utils import import_pynvml
from vllm.utils.torch_utils import is_quantized_kv_cache
from vllm.v1.attention.backends.registry import AttentionBackendEnum
from .interface import DeviceCapability, Platform, PlatformEnum
from .interface import DeviceCapability, Platform, PlatformEnum, in_wsl
if TYPE_CHECKING:
from vllm.config import VllmConfig
@@ -159,6 +160,21 @@ def with_nvml_context(fn: Callable[_P, _R]) -> Callable[_P, _R]:
return wrapper
@cache
def _get_wsl_kernel_version() -> tuple[int, ...] | None:
"""Return the WSL2 kernel version as a tuple, or None on parse failure.
platform.uname().release on WSL2 looks like
"5.15.167.4-microsoft-standard-WSL2"; we take the numeric prefix.
"""
try:
release = platform.uname().release
parts = release.split("-")[0].split(".")
return tuple(int(x) for x in parts[:3])
except Exception:
return None
class CudaPlatformBase(Platform):
_enum = PlatformEnum.CUDA
device_name: str = "cuda"
@@ -224,6 +240,27 @@ class CudaPlatformBase(Platform):
def log_warnings(cls):
pass
@classmethod
def is_pin_memory_available(cls) -> bool:
if in_wsl():
# WSL1 has no CUDA support, so being on the CUDA platform under
# WSL implies WSL2. Gate on kernel >= 4.19.121, the first WSL2
# kernel with limited pinned memory support for CUDA.
version = _get_wsl_kernel_version()
if version is None or version < (4, 19, 121):
logger.warning(
"Using 'pin_memory=False' as WSL is detected and the "
"WSL2 kernel version is below 4.19.121. This may slow "
"down performance. Please run `wsl --update`."
)
return False
# On compatible WSL2 kernels, pinned memory is supported but
# disabled by default. Enable it via VLLM_WSL2_ENABLE_PIN_MEMORY=1.
import vllm.envs as envs
return envs.VLLM_WSL2_ENABLE_PIN_MEMORY
return True
@classmethod
def check_and_update_config(cls, vllm_config: VllmConfig) -> None:
parallel_config = vllm_config.parallel_config
@@ -246,6 +283,27 @@ class CudaPlatformBase(Platform):
)
scheduler_config.disable_chunked_mm_input = True
if (
in_wsl()
and vllm_config.offload_config.uva.cpu_offload_gb > 0
and bool(vllm_config.compilation_config.cudagraph_mode)
):
logger.warning(
"--cpu-offload-gb is enabled with CUDA graphs on WSL2. "
"This combination requires pinned (page-locked) memory "
"allocations. WARNING: Windows (WDDM) enforces a hard "
"system-wide cap of roughly 50%% of physical RAM on pinned "
"memory shared across ALL processes by default (limit can "
"changed via %%USERPROFILE%%\\.wslconfig). "
"Excessive use of page-locked memory can prevent Windows "
"from reclaiming memory under load, which can cause the "
"entire host OS to become unresponsive and may require a "
"hard reboot to recover. Proceed at your own risk. "
"To raise the WSL2 VM memory ceiling, increase the `memory` "
"setting in %%USERPROFILE%%\\.wslconfig and run "
"`wsl --shutdown`."
)
@classmethod
def get_current_memory_usage(
cls, device: torch.types.Device | None = None
+6 -2
View File
@@ -2,6 +2,7 @@
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
import contextlib
import enum
import functools
import os
import platform
import sys
@@ -30,6 +31,7 @@ else:
logger = init_logger(__name__)
@functools.cache
def in_wsl() -> bool:
# Reference: https://github.com/microsoft/WSL/issues/4071
return "microsoft" in " ".join(platform.uname()).lower()
@@ -752,11 +754,13 @@ class Platform:
def is_pin_memory_available(cls) -> bool:
"""Checks whether pin memory is available on the current platform."""
if in_wsl():
# Pinning memory in WSL is not supported.
# https://docs.nvidia.com/cuda/wsl-user-guide/index.html#known-limitations-for-linux-cuda-applications
# Pinned memory support under WSL depends on the vendor and driver
# version. Conservative default: return False. Platform subclasses
# that can verify support (e.g. CudaPlatformBase) override this.
logger.warning(
"Using 'pin_memory=False' as WSL is detected. "
"This may slow down the performance."
"This may slow down performance."
)
return False
return True