Skip to main content

​
Overview

This guide covers the complete installation process for Gentleman.Dots on Windows using the Windows Subsystem for Linux (WSL). This is the only supported method for running Gentleman.Dots on Windows.
Important: Windows users must follow the manual installation instructions in this guide before running the automated script. The WSL setup requires specific Windows-side configuration steps.

​
Why WSL?

WSL (Windows Subsystem for Linux) allows you to run a Linux environment directly on Windows without the overhead of a traditional virtual machine. This provides:
  • Native Linux performance for development tools
  • Full compatibility with Linux-based dotfiles and configurations
  • Seamless integration between Windows and Linux filesystems
  • Access to both Windows and Linux tools simultaneously

​
Prerequisites

  • Windows 10 version 2004 or higher (Build 19041 and higher) or Windows 11
  • Administrator privileges on Windows
  • Virtualization enabled in BIOS/UEFI
  • At least 4GB of free disk space
  • Internet connection for downloading packages

​
Installation Steps

1

Install WSL

Open PowerShell or Windows Command Prompt as Administrator and run:
wsl --install
wsl --set-default-version 2
This command will:
  • Enable the required WSL features
  • Install the WSL 2 kernel
  • Set WSL 2 as the default version
  • Install Ubuntu by default
After installation, you may need to restart your computer.
2

Install a Linux Distribution

Install Ubuntu (recommended) or your preferred Linux distribution:
wsl --install -d Ubuntu
Ubuntu is recommended as it has the best compatibility with the installation script and package repositories.
3

Launch and Configure the Distribution

  1. Launch the installed distribution from the Start menu
  2. Create a username and password when prompted
  3. Update the system packages:
sudo apt-get update
sudo apt-get upgrade -y
4

Install Iosevka Term Nerd Font (Windows)

The Nerd Font must be installed on Windows, not in WSL:
  1. Download the Iosevka Term Nerd Font:
  2. Extract the ZIP file to a folder
  3. Install the fonts:
    • Select all .ttf or .otf files
    • Right-click and select “Install for all users”
Installing fonts only for the current user may cause issues with terminal emulators. Always install “for all users”.
5

Install a Terminal Emulator (Windows)

Choose and install a terminal emulator on Windows (not in WSL):
  1. Download from GitHub Releases
  2. Extract and place alacritty.exe in a folder added to your PATH
  3. Or use a package manager like Scoop: 
    scoop install alacritty
6

Configure Terminal Emulator for WSL

Configure your terminal emulator to launch WSL by default:
  1. Copy the Alacritty configuration to Windows: 
    mkdir $env:APPDATA\alacritty
Copy-Item -Path alacritty.toml -Destination $env:APPDATA\alacritty\alacritty.toml
  2. Edit alacritty.toml and uncomment these lines: 
    [shell]
program = "wsl.exe"
args = ["--cd", "~"]
7

Install Chocolatey and win32yank

Install Chocolatey (Windows package manager) and win32yank for clipboard integration:Open PowerShell as Administrator and run:
Set-ExecutionPolicy Bypass -Scope Process -Force; `
[System.Net.ServicePointManager]::SecurityProtocol = `
[System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex
Then install win32yank:
choco install win32yank
win32yank is essential for clipboard integration in Neovim when using WSL. Without it, you won’t be able to copy/paste between Windows and Neovim.
8

Install Gentleman.Dots in WSL

Now, inside your WSL Ubuntu terminal, follow the Linux installation process:
# Download the installation script
curl -O https://raw.githubusercontent.com/Gentleman-Programming/Gentleman.Dots/refs/heads/main/install-linux-mac.sh

# Make it executable
sudo chmod +x install-linux-mac.sh

# Run the installation
bash ./install-linux-mac.sh
The script will:
  • Install all required dependencies in WSL
  • Configure your chosen shell
  • Set up your window manager (Tmux/Zellij)
  • Install and configure Neovim with AI integrations
When prompted for operating system, select “linux” since you’re running inside WSL.
9

Restart Your Terminal

Close and reopen your terminal emulator, or restart WSL:
# From PowerShell (restarts WSL)
wsl --shutdown
Then launch your terminal emulator again.

​
WSL-Specific Considerations

​
File System Performance

Important: Always work within the WSL filesystem (/home/...) rather than the Windows filesystem (/mnt/c/...) for best performance.
# Good - Fast (WSL filesystem)
cd ~/projects
git clone ...

# Bad - Slow (Windows filesystem via WSL)
cd /mnt/c/Users/YourName/projects
git clone ...

​
Accessing Windows Files from WSL

Windows drives are mounted under /mnt/:
  • C:\ → /mnt/c/
  • D:\ → /mnt/d/
# Access Windows desktop from WSL
cd /mnt/c/Users/YourName/Desktop

​
Accessing WSL Files from Windows

You can access WSL files from Windows Explorer: 
\\wsl$\Ubuntu\home\username
Or type in File Explorer address bar: 
\\wsl$

​
Running Windows Applications from WSL

You can launch Windows applications from WSL: 
# Open current directory in Windows Explorer
explorer.exe .

# Open a file with default Windows application
cmd.exe /c start myfile.pdf

# Use VS Code (if installed on Windows)
code .

​
Memory Management

WSL 2 can consume a lot of memory. To limit it, create .wslconfig in your Windows home directory: 
# C:\Users\YourName\.wslconfig
[wsl2]
memory=4GB
processors=4
Then restart WSL: 
wsl --shutdown

​
Troubleshooting

If WSL installation fails:
  1. Ensure virtualization is enabled in BIOS/UEFI
  2. Enable Windows features manually: 
    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  3. Restart your computer
  4. Download and install the WSL2 Linux kernel update
If your terminal can’t connect to WSL:
  1. Verify WSL is running: 
    wsl --list --verbose
  2. Start WSL manually: 
    wsl
  3. Check terminal emulator WSL configuration (see Step 6)
If clipboard integration doesn’t work:
  1. Verify win32yank is installed: 
    choco list win32yank
  2. Ensure it’s in Windows PATH: 
    where.exe win32yank
  3. Test from WSL: 
    echo "test" | win32yank.exe -i
win32yank.exe -o
If Nerd Font icons don’t display:
  1. Verify font is installed on Windows (not WSL)
  2. Check font name in terminal emulator config matches exactly
  3. Restart terminal emulator completely
  4. In Windows Terminal, set font to “IosevkaTerm Nerd Font” in Settings
If WSL performance is slow:
  1. Ensure you’re working in WSL filesystem (~/...), not Windows (/mnt/c/...)
  2. Move projects to WSL: 
    cp -r /mnt/c/Users/YourName/projects ~/projects
  3. Consider limiting WSL memory usage (see Memory Management above)
  4. Check if antivirus is scanning WSL files (add exclusion if needed)
If WSL stops working after a Windows update:
  1. Update WSL: 
    wsl --update
  2. Restart WSL: 
    wsl --shutdown
wsl
  3. If still broken, reinstall the distribution (this will delete data): 
    wsl --unregister Ubuntu
wsl --install -d Ubuntu

​
WSL Commands Reference

wsl --list --verbose

​
Next Steps

Customize Your Setup

Learn how to customize terminal colors, key bindings, and more

Neovim Configuration

Explore Neovim features and AI integrations

WSL Best Practices

Learn more about WSL from Microsoft’s official documentation

Join the Community

Get help and share your setup with the community
Pro Tip: Install the “Remote - WSL” extension in VS Code to seamlessly develop in WSL with full IDE integration!

Build docs developers (and LLMs) love

Get started for freeTalk to us