My minimal setup for Arch Linux development environment optimized for WSL2, designed for daily workflow. This setup combines essential tools and configurations to create a powerful yet minimalist development workspace.

Mirror on my Git

⚠️ If you encounter an issue with slow startup of docker.service, the simplest solution is to disable systemd-networkd-wait-online:

sudo systemctl disable systemd-networkd-wait-online

See: https://github.com/yuk7/ArchWSL/issues/356

Features

Core Components

OS: Arch Linux on WSL2
Terminal: WezTerm
Shell: Fish
Multiplexer: Tmux
Prompt: Starship

Additional Tools

Package Manager: paru
Editor: Neovim
System Info: fastfetch
File Listing: exa
System Monitor: htop

Installation

Software Requirements

Windows 10 version 2004 (build 19041) or higher / Windows 11
Windows Subsystem for Linux (WSL2) component enabled (WSL1 is not supported)
Virtual Machine Platform feature enabled
Windows Terminal (optional but recommended for initial setup)
Git for Windows

Note: WSL2 is configured to use up to 16GB of RAM in this setup (can be adjusted in .wslconfig)

1. Windows Host Setup

# Install WezTerm (or download directly: https://wezterm.org/install/windows.html)
winget install wezterm

# Clone repository
git clone https://github.com/xzeldon/dotfiles-wsl2
cd dotfiles-wsl2

# Copy Windows configs (THIS WILL OVERWRITE FILES IF THEY EXIST!)
Copy-Item -Path ".\windows\*" -Destination $HOME -Force -Recurse

2. Arch Linux WSL Setup

Download the latest Arch Linux WSL image (you need .wsl file)
Import to WSL2:

wsl --import NAME INSTALL_PATH IMAGE_PATH

Where:

NAME: Your preferred WSL distribution name (e.g., "Arch")
INSTALL_PATH: Where to store the WSL2 virtual disk (e.g., "D:\wsl\Arch")
IMAGE_PATH: Path to the downloaded Arch Linux image (e.g., "D:\Downloads\archlinux-latest.wsl")

Example:

wsl --import Arch D:\wsl\Arch "D:\Downloads\archlinux-latest.wsl"

3. System Configuration

Automatic Setup Script (Recommended)

The repository includes an automated setup script that performs all the configuration steps described in the manual setup.

# Run the setup script with default values (Distribution: "Arch", Username: "user")
.\Install.ps1

# Or specify your own distribution name and username
.\Install.ps1 -DistroName "YourDistroName" -Username "yourusername"

⚠️ Important Notes About Automatic Setup

Configuration Overwriting: The script will overwrite the WezTerm configuration file in your Windows home directory. If you have a custom WezTerm setup, make sure to back it up before running the script.
Error Handling: The script does not comprehensively handle all possible errors. If something goes wrong (e.g., incorrect password confirmation, package installation failures), the script will continue execution regardless.
Network Requirements: A stable internet connection is required. Using VPNs or proxies is not recommended due to WSL networking limitations.
User Interaction: You will need to enter passwords for the root and user accounts during script execution.

After the script completes:

Start your WSL distribution: wsl -d YourDistroName
Open tmux and install plugins by pressing Ctrl+Space followed by Shift+I
Edit tmux.conf to specify which disk will be displayed in the status bar.
The recommended way to use this WSL setup is through WezTerm. After all configurations are complete, launch WezTerm and you should see tmux running with 3 panes automatically.

Manual Setup

⚠️ Note: Throughout this guide, we'll use:

Distribution name: Arch (if you choose a different name, update it in WezTerm config under default_domain = "WSL:Arch")

Username: user (if you want a different username, update relevant configs like ./wsl/etc/wsl.conf)

If you prefer a manual setup or need more control over the installation process, follow these steps:

Initial System Setup

# Run first-time setup
/usr/lib/wsl/first-setup.sh

# Update system
pacman -Syu

# Install dependencies
pacman -S sudo git vim neovim openssh wget binutils less debugedit fakeroot \
          fastfetch starship exa fish tmux htop python base-devel go dos2unix

User Configuration

# Set root user password
passwd

# Configure locale
echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
locale-gen

# Create user
useradd -m user

# Set user password
passwd user

# Configure sudo
echo "user ALL=(ALL) ALL" >> /etc/sudoers.d/user

WSL Configuration

# On Windows (PowerShell):
# Assuming:
# - You're in the repository root directory
# - Your WSL distribution is named "Arch" (from section 2.2)
# Copy WSL configuration file from host to guest
cp .\wsl\etc\wsl.conf \\wsl.localhost\Arch\etc\wsl.conf

# In WSL (Arch Linux):
# Convert line endings from Windows (CRLF) to Unix (LF) format
dos2unix /etc/wsl.conf

# On Windows (PowerShell):
# Restart WSL to apply changes
wsl --shutdown

AUR Helper and SSH Bridge Setup

# Install AUR helper
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin
makepkg -si

# Install agent for ssh bridge
# (see: https://wiki.archlinux.org/title/Install_Arch_Linux_on_WSL#Bridge_the_ssh-agent_service_from_Windows)
paru -S wsl2-ssh-agent

# Create .ssh directory (this does not exist by default, but is required for wsl2-ssh-agent)
mkdir ~/.ssh

Copy Configuration Files

# From Windows PowerShell:
# Assuming you're in the repo directory, `Arch` is your WSL distribution name and username is `user`
Copy-Item -Path .\wsl\* -Destination \\wsl.localhost\Arch\home\user -Recurse -Force -Exclude "etc"

Tmux Setup

# Install Tmux Plugin Manager
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Start tmux and install plugins
tmux # Then press Ctrl+Space, Shift+I

Configuration

File Structure

├── windows/                # Windows-side configs
│   ├── .wezterm.lua       # WezTerm configuration
│   └── .wslconfig         # WSL global settings
└── wsl/                   # Linux-side configs
    ├── .config/
    │   ├── fish/         # Fish shell configuration
    │   ├── tmux/         # Tmux configuration
    │   └── starship.toml # Prompt configuration
    └── etc/
        └── wsl.conf      # WSL distribution settings

Key Bindings

Tmux

Binding	Action
`Ctrl + Space`	Tmux prefix
`Prefix + I`	Install Tmux plugins
`Prefix + c`	Create new pane
`Prefix + %`	Create new pane vertically
`Prefix + "`	Create new pane horizontally
`Prefix + x`	Kill current pane

WezTerm

Binding	Action
`Ctrl + Shift + Q`	Close WezTerm window
`Ctrl + Shift + M`	Minimize WezTerm window
`Ctrl + Shift + Left Mouse Button`	Drag to move mode

Tip: use fish_add_path /some/path/bin to add directories to $PATH. See: https://fishshell.com/docs/current/cmds/fish_add_path.html

README.md

WSL2 Arch Linux Development Environment