Bug: NVML Fails To Initialize In WSL With VLLM

It appears there's a bug causing NVML (NVIDIA Management Library) to fail initialization when running a basic vLLM example on the Windows Subsystem for Linux (WSL). This issue seems to stem from the fork multiprocessing method used in WSL. Let's dive into the details and see how we can address this.

Understanding the Issue

When running the basic example provided in the vLLM documentation, users are encountering an NVMLError_NotSupported error. This error occurs during the initialization of the LLM engine, specifically when the code attempts to initialize NVML. The traceback indicates that the failure happens within the vllm.third_party.pynvml module, which is responsible for interacting with the NVIDIA drivers.

The root cause appears to be related to how WSL handles the fork multiprocessing method. In a nutshell, when a new process is created using fork, it inherits the memory space of the parent process. However, this inheritance can sometimes lead to issues when dealing with low-level libraries like NVML, which rely on specific hardware and driver configurations.

To confirm this, a minimal script was created to reproduce the issue. This script mimics the NVML initialization process within a child process created using fork. The results showed that the NVML initialization fails specifically in the child process, while it succeeds in the parent process. Moreover, when the multiprocessing method is hardcoded to spawn instead of fork, the issue disappears. This further strengthens the hypothesis that the fork method is the culprit.

Environment Details

The issue was observed in the following environment:

• Operating System: Ubuntu 22.04.5 LTS (x86_64) running on WSL2
• GPU: NVIDIA GeForce RTX 3070
• Nvidia Driver Version: 581.80
• CUDA Version: 12.8.61
• PyTorch Version: 2.9.1+cu129
• vLLM Version: 0.14.0rc1.dev479+g2a4dbe24e.d20260112
• Python Version: 3.12.12

The environment details confirm that the issue is not related to outdated drivers or incompatible CUDA versions. Instead, it seems to be a specific interaction between NVML, the fork multiprocessing method, and the WSL environment.

Reproduction Steps

To reproduce the issue, follow these steps:

1. Install vLLM in a WSL environment with the specified configurations.
2. Run the basic example provided in the vLLM documentation:

   (vllm) $ python examples/offline_inference/basic/basic.py
   

3. Observe the NVMLError_NotSupported error during the LLM engine initialization.

Alternatively, you can use the provided minimal script to reproduce the issue:

import multiprocessing
import os
import sys
import contextlib


def child_target():
    """Child process target function - tries to import and init NVML."""
    print(f"[CHILD {os.getpid()}] Starting child process")
    
    try:
        from vllm.utils.import_utils import import_pynvml
        pynvml = import_pynvml()
        pynvml.nvmlInit()
        print("!!!nvmlInit in child")
        print(pynvml.nvmlDeviceGetCount())
        pynvml.nvmlShutdown()
        print("!!!nvmlShutdown in child")

        sys.exit(0)
    except Exception as e:
        print(f"[CHILD] ✗ FAILED: {type(e).__name__}: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)


def main():
    print("=" * 70)
    print("NVML Initialization Test (WSL Reproduction)")
    print("=" * 70)
    print(f"[PARENT {os.getpid()}] Starting test\n")
    
    # Match basic.py: Check CUDA availability but DON'T initialize it
    print("[PARENT] Checking CUDA availability...")
    import torch
    print(f"[PARENT] CUDA available: {torch.cuda.is_available()}")
    print(f"[PARENT] Device count: {torch.cuda.device_count()}")
    print(f"[PARENT] CUDA initialized: {torch.cuda.is_initialized()}\n")
    # Note: We intentionally DON'T initialize CUDA here to match basic.py
    
    # Use get_mp_context() like vLLM does - it will use fork since CUDA not initialized
    print("[PARENT] Getting multiprocessing context...")
    from vllm.utils.system_utils import get_mp_context
    context = get_mp_context()
    print(f"[PARENT] Using context method: {context.get_start_method()}\n")
    
    # Create process object (like lines 120-128)
    print("[PARENT] Creating process object...")
    proc = context.Process(
        target=child_target,
        name="NVMLTestChild"
    )
    
    # Before starting, do NVML init/shutdown in parent (like lines 162-169)
    print("\n[PARENT] NVML init/shutdown before proc.start()...")
    with contextlib.nullcontext():
        print("[PARENT] Importing pynvml...")
        from vllm.utils.import_utils import import_pynvml
        pynvml = import_pynvml()
        
        print("[PARENT] Calling nvmlInit()...")
        pynvml.nvmlInit()
        print("[PARENT] ✓ nvmlInit() succeeded")
        
        device_count = pynvml.nvmlDeviceGetCount()
        print(f"[PARENT] Device count: {device_count}")
        
        print("[PARENT] Calling nvmlShutdown()...")
        pynvml.nvmlShutdown()
        print("[PARENT] ✓ nvmlShutdown() succeeded")
        print("[PARENT] Done with NVML init/shutdown cycle\n")
    
    # Now start the process (like line 172)
    print("[PARENT] Starting child process...")
    proc.start()
    proc.join()
    
    exit_code = proc.exitcode
    
    print("\n" + "=" * 70)
    print("RESULT")
    print("=" * 70)
    if exit_code == 0:
        print("✓ SUCCESS - No NVML initialization failure")
    else:
        print("✗ FAILED - NVML initialization issue reproduced!")
    
    return exit_code


if __name__ == "__main__":
    sys.exit(main())

Proposed Solution

The suggested solution is to update the _maybe_force_spawn function in vllm/utils/system_utils.py to also check if the code is running in a WSL environment. If it is, the multiprocessing method should be forced to spawn instead of fork. This can be achieved by adding a check for the WSL environment using os.environ or a similar mechanism.

Here's the relevant code snippet from vllm/utils/system_utils.py:

def _maybe_force_spawn() -> None:
    # If CUDA is not initialized, we force the multiprocess start method to be
    # 'spawn'. This is to avoid potential issues with CUDA context sharing when
    # using 'fork'.
    try:
        import torch
        if not torch.cuda.is_initialized():
            # Force the use of the