Host RAM Allocation (.wslconfig)
By default, WSL2 can consume up to 50% of your total system RAM. Create %USERPROFILE%\.wslconfig to cap resource consumption:
[wsl2]
memory=8GB
processors=4
[experimental]
autoMemoryReclaim=gradual
Windows Guide
Run tmux on Windows
tmux is a Unix-native tool and does not run on Windows natively. The recommended way to experience tmux on Windows is through WSL2 (Windows Subsystem for Linux 2), which provides a real Linux kernel. Alternatives include MSYS2 and Cygwin, though they provide a less complete experience.
WSL and Windows Terminal settings checked against Microsoft's documentation (October 2026)
Method 1: WSL2 (Recommended)
WSL2 provides a complete Linux environment inside Windows with full system call compatibility, making tmux work exactly as it does natively on Linux.
1
Enable WSL2
Open PowerShell as Administrator and run:
PowerShell (Administrator)
PS> wsl --install
# Installs WSL2 + Ubuntu by default. Restart when prompted.
For a specific distro, list the names with wsl --list --online, then e.g. wsl --install -d Ubuntu-24.04
2
Restart your PC
WSL2 requires a restart to complete installation. After restarting, Ubuntu will launch automatically on first boot and ask you to set up a username and password.
3
Install tmux inside Ubuntu (WSL2)
Ubuntu (WSL2)
$ sudo apt update && sudo apt install tmux
$ tmux -V
tmux 3.4 (Ubuntu 24.04; 3.6a on Ubuntu 26.04)
Windows Terminal Integration & Keybinding Optimization
Windows Terminal is the modern terminal host for WSL2. Configure it for seamless tmux navigation.
🚀 Dedicated tmux Profile
Create a dedicated Windows Terminal profile that attaches directly to a named default tmux session upon opening:
settings.json (profile commandLine)
wsl.exe -d Ubuntu -e tmux new-session -A -s main
The -A flag automatically attaches to the session if it exists, or creates it if it doesn't.
⌨️ Fixing Key Collision Conflicts
Windows Terminal handles some keys itself before tmux or Neovim sees them. These are its defaults; remove the ones you need under Settings → Actions:
- Alt+Arrow keys: move focus between Windows Terminal panes. This clashes with popular tmux bindings such as
bind -n M-Left select-pane -L. - Ctrl+Shift+W: close the Windows Terminal pane.
- Ctrl+Shift+D duplicates the tab and Alt+Shift+D splits the pane: free them if you bind these in Neovim.
- Alt+Enter / F11: toggle full screen.
📋 Bidirectional Windows Clipboard Sync
Synchronize tmux copy mode with the Windows system clipboard using clip.exe and PowerShell:
~/.tmux.conf
# Copy from tmux to Windows clipboard
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe"
bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "clip.exe"
# Paste from Windows clipboard into tmux
bind P run "powershell.exe -c Get-Clipboard | tmux load-buffer - ; tmux paste-buffer"
WSL2 Performance, RAM Limits & Persistence
Prevent WSL2 from consuming excessive host RAM and keep sessions alive across terminal windows.
Keeping Sessions Alive
WSL shuts a distribution down after it has been idle for 15 seconds (the instanceIdleTimeout default), which can kill a detached tmux server. To keep it running, add this to %UserProfile%\.wslconfig and run wsl --shutdown once:
[general]
instanceIdleTimeout=-1
For reboots, the tmux-resurrect and tmux-continuum plugins save your layout every 15 minutes.
Nerd Fonts & Powerline Glyph Setup
Install a patched font (like JetBrains Mono Nerd Font) in Windows, then select it in Windows Terminal settings under Profiles → Appearance → Font face for flawless status bar icons.
Method 2: MSYS2
MSYS2 provides a lightweight Unix-like environment on Windows without requiring a full Linux kernel. Suitable for simpler setups.
MSYS2 Shell
# Install MSYS2 from https://www.msys2.org first, then:
$ pacman -Syu
$ pacman -S tmux
$ tmux -V
Limitation: MSYS2 lacks a real Linux kernel — some tmux features (like socket-based session sharing) may behave differently than on native Linux or WSL2.
Method 3: Cygwin
Cygwin provides a POSIX-compatible layer for Windows. Recommended only for legacy environments.
Installing tmux via Cygwin Setup
- Download the Cygwin installer from cygwin.com
- Run the installer and select a mirror
- In the package selection screen, search for
tmux - Select the
tmuxpackage from the Net or Utils category - Complete installation and open the Cygwin terminal
- Verify:
tmux -V
⚠️ Limitation: Cygwin doesn't provide a real Linux kernel. tmux works, but session sharing, socket handling, and some system calls may behave differently. WSL2 is strongly preferred for a complete tmux experience.
Troubleshooting on Windows
Common WSL2 issues
If WSL2 fails to install, ensure virtualization is enabled in your BIOS/UEFI settings. Check WSL status with
wsl --status in PowerShell. Update WSL2 with wsl --update. If you get "WSL 2 requires an update to its kernel component", run wsl --update in an elevated PowerShell prompt.
tmux: no server running on /tmp/tmux-XXXX/default
This means no tmux server is running. Start a new session with
tmux new. If the socket directory doesn't exist, it may have been cleaned up. Ensure /tmp is writable in your WSL2 environment: ls -la /tmp. If WSL2 was restarted, existing tmux sessions will have been lost.
Colors or fonts not rendering correctly
Add
set -g default-terminal "tmux-256color" to your ~/.tmux.conf. Windows Terminal supports 24-bit colour, so also add set -as terminal-features ",xterm-256color:RGB". Install a Nerd Font (e.g., JetBrains Mono Nerd Font) from nerdfonts.com and set it as your Windows Terminal font for proper powerline/icon support.
tmux sessions lost when WSL2 restarts
WSL2 can shut down automatically when all Windows Terminal tabs are closed. To keep sessions alive, install
tmux-resurrect and tmux-continuum plugins. To stop WSL shutting down an idle distribution (and your tmux server with it), set instanceIdleTimeout=-1 under [general] in %UserProfile%\.wslconfig, then run wsl --shutdown so it takes effect.