Windows batch script to navigate CMD to WSL filesystem paths by converting POSIX paths to UNC and using pushd

goWSLPath.cmd

@echo off
setlocal enabledelayedexpansion
REM --------------------------------------------------------------------
REM Script: goWSLPath.cmd
REM Purpose:
REM   1. Accept a POSIX path as a mandatory argument.
REM   2. Determine the default WSL distribution.
REM   3. Convert the supplied POSIX path to a Windows UNC path.
REM   4. Use pushd to map the UNC path to a drive letter and change into it.
REM --------------------------------------------------------------------

REM 1. Verify that a POSIX path was provided.
if "%~1"=="" (
    echo Usage: %~nx0 POSIX_path
    echo Example: %~nx0 /home/path/to/my/folder
    exit /b 1
)
set "posixPath=%~1"

REM 2. Determine WSL distribution by testing UNC paths directly
set "distro="

REM Since WSL text parsing has Unicode issues, test actual UNC accessibility instead
for %%D in (Ubuntu-22.04 Ubuntu-20.04 Ubuntu-24.04 Ubuntu) do (
    if not defined distro (
        echo Testing WSL distribution: %%D
        pushd "\\wsl$\%%D\" >nul 2>&1
        if not errorlevel 1 (
            popd >nul 2>&1
            set "distro=%%D"
            echo Found working distribution: %%D
        ) else (
            echo Distribution %%D not accessible
        )
    )
)

if not defined distro (
    echo Could not find any accessible WSL distribution.
    echo Available distributions:
    wsl -l
    echo.
    echo Make sure WSL is running and try:
    echo   wsl --set-default ^<distribution-name^>
    exit /b 1
)

REM 3. Convert the supplied POSIX path to a Windows UNC subpath.
set "uncSubPath=%posixPath:/=\%"
set "uncPath=\\wsl$\!distro!!uncSubPath!"

echo Converting:
echo   POSIX path: %posixPath%
echo   WSL distro: !distro!
echo   to UNC path: !uncPath!

REM 4. Use pushd to map the UNC path to a drive letter and change into it.
pushd "!uncPath!"
if errorlevel 1 (
    echo Failed to access: !uncPath!
    echo Please verify:
    echo   1. WSL distribution '!distro!' is running
    echo   2. Path exists in WSL: %posixPath%
    exit /b 1
)

echo Successfully changed directory to !uncPath!
echo Current drive letter: %CD:~0,2%
echo.
echo You are now in the WSL directory. Type 'exit' to return to your original location.

REM Stay in the new directory by launching a new command prompt
cmd /k "echo Welcome to WSL directory: %CD%"

WSL-Navigation-Guide.md

WSL Navigation Guide

Overview

goWSLPath.cmd is a Windows batch script that allows seamless navigation from Windows Command Prompt to WSL (Windows Subsystem for Linux) filesystem paths. It automatically detects your WSL distribution, converts POSIX paths to Windows UNC paths, and uses pushd to map them to drive letters.

Usage

goWSLPath.cmd <posix_path>

Example:

goWSLPath.cmd /home/path/to/my/folder

This will:

1. Auto-detect your WSL distribution (e.g., Ubuntu-22.04)
2. Convert /home/path/to/my/folder to \\wsl$\Ubuntu-22.04\home\path\to\my\folder
3. Map it to a drive letter (e.g., Z:) and navigate there
4. Launch a new command prompt session in that location

Key Features

• Auto-detection: Automatically finds your active WSL distribution
• Error handling: Provides clear feedback if paths don't exist or WSL isn't running
• UNC mapping: Uses Windows' built-in pushd to create temporary drive mappings
• Unicode-safe: Avoids text parsing issues by testing actual filesystem accessibility

Technical Lessons Learned

1. WSL Output Encoding Issues

Problem: WSL commands (wsl -l, wsl -l -v) output text in UTF-16 encoding with Unicode BOM, making it impossible to parse reliably with standard batch for /F loops.

Evidence:

• type command displays the text correctly
• findstr patterns fail even on clearly visible text
• for /F loops find zero lines despite file containing data

Solution: Instead of parsing WSL text output, test actual UNC path accessibility using pushd commands.

2. Batch Script Directory Context

Problem: When a batch script finishes execution, Windows automatically returns to the original directory, undoing any pushd operations.

Solution: Launch a new command prompt session (cmd /k) within the target directory to maintain the navigation context.

3. Robust WSL Distribution Detection

Problem: Different WSL versions format output differently, and parsing asterisks or "(Default)" markers is unreliable due to encoding.

Solution: Test common distribution names by attempting to access their UNC paths (\\wsl$\<distro>\) directly.

4. Variable Expansion in Batch Files

Critical: Always use setlocal enabledelayedexpansion and !variable! syntax when variables are modified within loops or conditional blocks.

5. Error Handling Best Practices

• Provide clear diagnostic output showing what the script is testing
• Include suggested remediation steps in error messages
• Test actual functionality rather than relying on text parsing

Alternative Usage Methods

Option 1: Direct Call (Recommended)

call goWSLPath.cmd /home/user/project

Option 2: Create Doskey Macro

doskey gwsl=call "C:\path\to\goWSLPath.cmd" $*
gwsl /home/user/project

Option 3: Add to PATH

Place the script in a directory in your PATH, then simply:

goWSLPath /home/user/project

Requirements

• Windows 10/11 with WSL installed and running
• At least one WSL distribution (Ubuntu variants supported)
• Command Prompt or PowerShell (not Windows Terminal's WSL tabs)

Troubleshooting

• "Could not find any accessible WSL distribution": Ensure WSL is running (wsl --status)
• "Failed to access path": Verify the POSIX path exists in WSL (wsl ls -la /path/to/directory)
• Script exits immediately: Use call command or run from within existing command prompt session