This page documents WSL integration functions that enable seamless interaction between PowerShell and WSL environments.
Quick Access Functions
Enter-WSL / wsl
Enter the default WSL distribution.
function Enter-WSL {
<#
.SYNOPSIS
Enter WSL (default distribution)
.EXAMPLE
wsl
#>
wsl.exe
}
Usage:
# Enter WSL
wsl
# Returns you to your WSL home directory
# Type 'exit' to return to PowerShell
wsl-here
Open the current Windows directory in WSL.
function wsl-here {
<#
.SYNOPSIS
Open current Windows directory in WSL
.EXAMPLE
wsl-here
#>
$wslPath = (Get-Location).Path -replace '\\', '/' -replace '^(\w):', { '/mnt/' + $_.Groups[1].Value.ToLower() }
wsl.exe --cd $wslPath
}
Usage:
# Navigate to a Windows directory
cd C:\Users\YourName\Projects\myapp
# Open same directory in WSL
wsl-here
# You're now in /mnt/c/Users/YourName/Projects/myapp
Windows paths are automatically converted to WSL mount paths (e.g., C:\Users becomes /mnt/c/Users).
File Transfer Functions
Copy-ToWSL
Copy files from Windows to WSL.
function Copy-ToWSL {
<#
.SYNOPSIS
Copy file from Windows to WSL home directory
.EXAMPLE
Copy-ToWSL myfile.txt
Copy-ToWSL myfile.txt ~/projects/
#>
param(
[Parameter(Mandatory=$true, Position=0)]
[string]$Source,
[Parameter(Position=1)]
[string]$Destination = "~/"
)
$wslSource = (Resolve-Path $Source).Path -replace '\\', '/' -replace '^(\w):', { '/mnt/' + $_.Groups[1].Value.ToLower() }
wsl.exe cp "$wslSource" "$Destination"
}
Usage:
# Copy file to WSL home directory
Copy-ToWSL config.json
# Copy to specific WSL path
Copy-ToWSL script.sh ~/bin/
# Copy with wildcard
Copy-ToWSL *.txt ~/documents/
Copy-FromWSL
Copy files from WSL to Windows.
function Copy-FromWSL {
<#
.SYNOPSIS
Copy file from WSL to current Windows directory
.EXAMPLE
Copy-FromWSL ~/myfile.txt
Copy-FromWSL ~/myfile.txt C:\Users\me\Desktop\
#>
param(
[Parameter(Mandatory=$true, Position=0)]
[string]$Source,
[Parameter(Position=1)]
[string]$Destination = "."
)
$winDest = (Resolve-Path $Destination).Path -replace '\\', '/' -replace '^(\w):', { '/mnt/' + $_.Groups[1].Value.ToLower() }
wsl.exe cp "$Source" "$winDest"
}
Usage:
# Copy from WSL home to current directory
Copy-FromWSL ~/.bashrc
# Copy to specific Windows path
Copy-FromWSL ~/script.sh C:\Users\YourName\Desktop\
# Copy entire directory
Copy-FromWSL -r ~/projects/myapp .
Ensure WSL paths use Linux-style forward slashes (/) and Windows paths use backslashes (\).
Command Execution
Invoke-WSL / wslrun
Run commands in WSL and return to PowerShell.
function Invoke-WSL {
<#
.SYNOPSIS
Run a command in WSL and return to PowerShell
.EXAMPLE
wslrun 'ls -la'
wslrun 'cat ~/.bashrc'
#>
param(
[Parameter(Mandatory=$true, Position=0, ValueFromRemainingArguments)]
[string[]]$Command
)
wsl.exe -e bash -c ($Command -join ' ')
}
Usage:
# Run single command
wslrun 'ls -la'
# Run command with pipes
wslrun 'cat ~/.bashrc | grep alias'
# Run complex commands
wslrun 'find . -name "*.js" | wc -l'
# Execute script
wslrun './build.sh'
Common Workflows
Development Workflow
# Work on project in Windows
cd C:\Projects\webapp
# Open same directory in WSL for Linux tools
wsl-here
# Back in PowerShell, run WSL commands
wslrun 'npm install'
wslrun 'npm run build'
Configuration Sync
# Copy Windows config to WSL
Copy-ToWSL .gitconfig ~/
Copy-ToWSL .npmrc ~/
# Copy WSL config to Windows for backup
Copy-FromWSL ~/.bashrc C:\Backup\
Copy-FromWSL ~/.zshrc C:\Backup\
Script Execution
# Run Linux build script from Windows
wslrun 'cd /mnt/c/Projects/myapp && ./build.sh'
# Check Linux environment
wslrun 'uname -a'
wslrun 'which node'
wslrun 'node --version'
Path Conversion
Understanding path conversion is key to WSL integration:
Windows to WSL Paths
| Windows Path | WSL Path |
|---|
C:\Users\Name | /mnt/c/Users/Name |
D:\Projects | /mnt/d/Projects |
E:\Data\files | /mnt/e/Data/files |
WSL to Windows Paths
| WSL Path | Windows Path |
|---|
/mnt/c/Users/Name | C:\Users\Name |
~/documents | /home/username/documents |
/etc/hosts | \\wsl$\Ubuntu\etc\hosts |
Access WSL filesystem from Windows using \\wsl$\<distro-name>\ network path.
Practical Examples
# Use grep (better than Windows findstr)
wslrun 'grep -r "function" *.js'
# Use sed for text processing
wslrun 'sed -i "s/old/new/g" file.txt'
# Use awk for data processing
wslrun 'cat data.csv | awk -F"," "{print $1}"'
# Run make commands
wslrun 'make clean'
wslrun 'make build'
# Run Docker in WSL
wslrun 'docker ps'
wslrun 'docker-compose up -d'
# Run Python/Node in WSL environment
wslrun 'python3 script.py'
wslrun 'node app.js'
File Operations
# Create symlink in WSL
wslrun 'ln -s /mnt/c/Projects/config ~/.config/myapp'
# Change permissions
wslrun 'chmod +x script.sh'
wslrun 'chown user:user file.txt'
# Check disk usage
wslrun 'du -sh *'
wslrun 'df -h'
Troubleshooting
WSL Not Found
# Check if WSL is installed
wsl --list --verbose
# Install WSL
wsl --install
# Set default distribution
wsl --set-default Ubuntu
Path Issues
# If paths don't resolve, check current location
Get-Location
# Use absolute paths
Copy-ToWSL C:\Users\Name\file.txt ~/
# Verify WSL can access Windows paths
wslrun 'ls /mnt/c/Users'
Permission Issues
# Run WSL as root if needed
wsl -u root -e bash -c 'command'
# Check file permissions in WSL
wslrun 'ls -la /path/to/file'
Be cautious when running commands as root. Always verify the command before execution.
Tips & Best Practices
-
Use wsl-here for development: When working on projects, use
wsl-here to seamlessly switch between Windows and Linux tools.
-
Keep scripts in WSL: Store build scripts and Linux-specific tools in your WSL home directory for faster access.
-
Mount Windows drives: All Windows drives are automatically mounted at
/mnt/<drive-letter> in WSL.
-
Performance: For better I/O performance, keep files in WSL filesystem rather than accessing through
/mnt/c.
-
Line endings: Be aware of CRLF (Windows) vs LF (Linux) line endings when sharing files.
# Convert line endings in WSL
wslrun 'dos2unix file.txt' # Windows to Linux
wslrun 'unix2dos file.txt' # Linux to Windows