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
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.
Verified for Windows 11 & 10 (WSL2 / Windows Terminal) · tmux v3.6a
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: wsl --install -d Ubuntu-22.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.x
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 intercepts several standard navigation shortcuts. Open Settings → Actions and unbind conflicting shortcuts:
- Ctrl+Shift+W: Close pane conflict (remap or disable).
- Ctrl+Shift+D: Split pane collision (unmap to let tmux handle pane splits).
- Alt+Enter: Fullscreen toggle vs Neovim keymaps.
📋 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
When all Windows Terminal tabs close, Windows may terminate the WSL2 VM after a timeout. Use the tmux-resurrect and tmux-continuum plugins to automatically 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. In Windows Terminal, ensure your color scheme supports 256 colors. 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. Also, you can prevent WSL2 from shutting down by keeping a background WSL2 process running, or by configuring %USERPROFILE%\.wslconfig with [wsl2] autoMemoryReclaim=disabled.