feat: add WSL (Windows Subsystem for Linux) detection and support

Add comprehensive WSL detection and tailored installation guidance for users
running promptfoo-python in Windows Subsystem for Linux.

Detection:
- Detects WSL via WSL_DISTRO_NAME and WSL_INTEROP environment variables
- Checks /proc/version for Microsoft/WSL signatures
- Detects WSL 1 via /mnt/c Windows filesystem mounts
- Integrated into environment detection system

Installation Guidance:
- Warns users NOT to use Windows Node.js from WSL (path/performance issues)
- Recommends installing Node.js within WSL using Linux package managers
- Provides nvm as recommended alternative for version management
- Includes WSL-specific performance tips (store files in ~/, not /mnt/c/)
- Shows both WSL guidance and Linux distro-specific instructions

Testing:
- Added 3 WSL detection tests (env vars, interop, no detection)
- Added 2 WSL instruction tests (basic, combined with Ubuntu)
- Added WSL Ubuntu environment detection test
- Updated all existing environment tests to mock WSL detection
- Total: 102 tests passing (6 new WSL-related tests)

This improves the developer experience for the large number of users who develop
in WSL, providing them with WSL-aware best practices instead of generic Linux
instructions that may lead to suboptimal configurations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: mldangelo

src/promptfoo/environment.py

@@ -25,6 +25,7 @@ class Environment:
     is_cloud_function: bool = False  # GCP Cloud Functions or Azure Functions
     is_docker: bool = False
     is_kubernetes: bool = False
+    is_wsl: bool = False  # Windows Subsystem for Linux
     is_ci: bool = False
     ci_platform: Optional[str] = None  # "github", "gitlab", "circleci", "jenkins", etc.
     is_venv: bool = False
@@ -171,6 +172,32 @@ def _detect_container() -> tuple[bool, bool]:
     return is_docker, is_kubernetes
 
 
+def _detect_wsl() -> bool:
+    """
+    Detect if running in Windows Subsystem for Linux (WSL).
+
+    Returns:
+        True if running in WSL, False otherwise
+    """
+    # Check for WSL environment variable
+    if os.getenv("WSL_DISTRO_NAME") or os.getenv("WSL_INTEROP"):
+        return True
+
+    # Check /proc/version for Microsoft/WSL signatures
+    if Path("/proc/version").exists():
+        try:
+            with open("/proc/version") as f:
+                version_info = f.read().lower()
+                if "microsoft" in version_info or "wsl" in version_info:
+                    return True
+        except OSError:
+            pass
+
+    # Check for Windows filesystem mounts (WSL mounts Windows drives at /mnt/)
+    # This is less reliable but can catch WSL 1
+    return Path("/mnt/c").exists() and Path("/proc/version").exists()
+
+
 def _detect_ci() -> tuple[bool, Optional[str]]:
     """
     Detect if running in a CI/CD environment.
@@ -284,6 +311,11 @@ def detect_environment() -> Environment:
     if os_type == "linux":
         is_docker, is_kubernetes = _detect_container()
 
+    # WSL detection
+    is_wsl = False
+    if os_type == "linux":
+        is_wsl = _detect_wsl()
+
     # CI detection
     is_ci, ci_platform = _detect_ci()
 
@@ -302,6 +334,7 @@ def detect_environment() -> Environment:
         is_cloud_function=is_cloud_function,
         is_docker=is_docker,
         is_kubernetes=is_kubernetes,
+        is_wsl=is_wsl,
         is_ci=is_ci,
         ci_platform=ci_platform,
         is_venv=is_venv,

src/promptfoo/instructions.py

@@ -42,6 +42,11 @@ def get_installation_instructions(env: Environment) -> str:
         lines.extend(_get_docker_instructions(env))
         lines.append("")
 
+    # WSL environment
+    if env.is_wsl:
+        lines.extend(_get_wsl_instructions())
+        lines.append("")
+
     # Platform-specific instructions
     if env.os_type == "linux":
         lines.extend(_get_linux_instructions(env))
@@ -182,6 +187,28 @@ def _get_docker_instructions(env: Environment) -> list[str]:
     return lines
 
 
+def _get_wsl_instructions() -> list[str]:
+    """Instructions for Windows Subsystem for Linux (WSL)."""
+    return [
+        "WINDOWS SUBSYSTEM FOR LINUX (WSL) DETECTED:",
+        "",
+        "IMPORTANT: Install Node.js within WSL, not from Windows.",
+        "Using Windows Node.js from WSL can cause path and performance issues.",
+        "",
+        "Recommended approach:",
+        "   1. Use your Linux distribution's package manager (see below)",
+        "   2. Or use nvm for version management:",
+        "      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash",
+        "      source ~/.bashrc",
+        "      nvm install 20",
+        "",
+        "Tips for WSL:",
+        "   - Store project files in the WSL filesystem (~/), not /mnt/c/",
+        "   - This improves file I/O performance significantly",
+        "   - Use 'wsl --shutdown' to restart WSL if needed",
+    ]
+
+
 def _get_linux_instructions(env: Environment) -> list[str]:
     """Instructions for Linux systems."""
     lines = []

tests/test_environment.py

@@ -109,6 +109,36 @@ def test_detect_container_returns_tuple(self) -> None:
         assert isinstance(is_k8s, bool)
 
 
+class TestWSLDetection:
+    """Test WSL detection."""
+
+    def test_detect_wsl_from_env_var(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detect WSL from WSL_DISTRO_NAME environment variable."""
+        monkeypatch.setenv("WSL_DISTRO_NAME", "Ubuntu")
+
+        from promptfoo.environment import _detect_wsl
+
+        assert _detect_wsl() is True
+
+    def test_detect_wsl_from_interop_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detect WSL from WSL_INTEROP environment variable."""
+        monkeypatch.setenv("WSL_INTEROP", "/run/WSL/123_interop")
+
+        from promptfoo.environment import _detect_wsl
+
+        assert _detect_wsl() is True
+
+    def test_no_wsl_detected(self) -> None:
+        """Return False when not in WSL."""
+        with mock.patch.dict(os.environ, {}, clear=True):
+            from promptfoo.environment import _detect_wsl
+
+            # This will return False unless we're actually in WSL
+            # Just verify it returns a boolean
+            result = _detect_wsl()
+            assert isinstance(result, bool)
+
+
 class TestCIDetection:
     """Test CI/CD platform detection."""
 
@@ -217,6 +247,7 @@ def test_detect_ubuntu_with_docker(self, monkeypatch: pytest.MonkeyPatch, tmp_pa
             mock.patch("sys.platform", "linux"),
             mock.patch("promptfoo.environment._detect_linux_distro", return_value=("ubuntu", "22.04")),
             mock.patch("promptfoo.environment._detect_container", return_value=(True, False)),
+            mock.patch("promptfoo.environment._detect_wsl", return_value=False),
             mock.patch("promptfoo.environment._detect_ci", return_value=(False, None)),
             mock.patch("promptfoo.environment._detect_cloud_provider", return_value=None),
             mock.patch("promptfoo.environment._detect_python_env", return_value=(True, False)),
@@ -229,6 +260,7 @@ def test_detect_ubuntu_with_docker(self, monkeypatch: pytest.MonkeyPatch, tmp_pa
             assert env.linux_distro_version == "22.04"
             assert env.is_docker is True
             assert env.is_kubernetes is False
+            assert env.is_wsl is False
             assert env.is_venv is True
 
     def test_detect_macos_environment(self) -> None:
@@ -267,6 +299,7 @@ def test_detect_aws_lambda(self, monkeypatch: pytest.MonkeyPatch) -> None:
             mock.patch("sys.platform", "linux"),
             mock.patch("promptfoo.environment._detect_linux_distro", return_value=("amzn", "2")),
             mock.patch("promptfoo.environment._detect_container", return_value=(False, False)),
+            mock.patch("promptfoo.environment._detect_wsl", return_value=False),
             mock.patch("promptfoo.environment._detect_ci", return_value=(False, None)),
             mock.patch("promptfoo.environment._detect_cloud_provider", return_value="aws"),
             mock.patch("promptfoo.environment._detect_python_env", return_value=(False, False)),
@@ -285,6 +318,7 @@ def test_detect_github_actions(self, monkeypatch: pytest.MonkeyPatch) -> None:
             mock.patch("sys.platform", "linux"),
             mock.patch("promptfoo.environment._detect_linux_distro", return_value=("ubuntu", "22.04")),
             mock.patch("promptfoo.environment._detect_container", return_value=(False, False)),
+            mock.patch("promptfoo.environment._detect_wsl", return_value=False),
             mock.patch("promptfoo.environment._detect_ci", return_value=(True, "github")),
             mock.patch("promptfoo.environment._detect_cloud_provider", return_value=None),
             mock.patch("promptfoo.environment._detect_python_env", return_value=(False, False)),
@@ -294,3 +328,24 @@ def test_detect_github_actions(self, monkeypatch: pytest.MonkeyPatch) -> None:
 
             assert env.is_ci is True
             assert env.ci_platform == "github"
+
+    def test_detect_wsl_ubuntu(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detect WSL with Ubuntu."""
+        monkeypatch.setenv("WSL_DISTRO_NAME", "Ubuntu")
+
+        with (
+            mock.patch("sys.platform", "linux"),
+            mock.patch("promptfoo.environment._detect_linux_distro", return_value=("ubuntu", "22.04")),
+            mock.patch("promptfoo.environment._detect_container", return_value=(False, False)),
+            mock.patch("promptfoo.environment._detect_wsl", return_value=True),
+            mock.patch("promptfoo.environment._detect_ci", return_value=(False, None)),
+            mock.patch("promptfoo.environment._detect_cloud_provider", return_value=None),
+            mock.patch("promptfoo.environment._detect_python_env", return_value=(False, False)),
+            mock.patch("promptfoo.environment._has_sudo_access", return_value=True),
+        ):
+            env = detect_environment()
+
+            assert env.os_type == "linux"
+            assert env.linux_distro == "ubuntu"
+            assert env.is_wsl is True
+            assert env.is_docker is False

tests/test_instructions.py

@@ -129,6 +129,41 @@ def test_docker_ubuntu_instructions(self) -> None:
         assert "Dockerfile" in instructions
 
 
+class TestWSLInstructions:
+    """Test instructions for WSL (Windows Subsystem for Linux)."""
+
+    def test_wsl_instructions(self) -> None:
+        """Generate WSL-specific instructions."""
+        env = Environment(
+            os_type="linux",
+            linux_distro="ubuntu",
+            is_wsl=True,
+        )
+
+        instructions = get_installation_instructions(env)
+
+        assert "WSL" in instructions or "Windows Subsystem for Linux" in instructions
+        assert "nvm" in instructions
+        assert "/mnt/c" in instructions  # Should mention Windows filesystem
+        assert "performance" in instructions.lower()
+
+    def test_wsl_with_ubuntu_shows_both(self) -> None:
+        """WSL instructions should show both WSL tips and Ubuntu instructions."""
+        env = Environment(
+            os_type="linux",
+            linux_distro="ubuntu",
+            is_wsl=True,
+            has_sudo=True,
+        )
+
+        instructions = get_installation_instructions(env)
+
+        # Should have WSL-specific guidance
+        assert "WSL" in instructions
+        # Should also have Ubuntu/Debian instructions
+        assert "UBUNTU" in instructions or "DEBIAN" in instructions
+
+
 class TestLinuxInstructions:
     """Test instructions for various Linux distributions."""