tmux Complete Guide for Beginners: Sessions, Windows, Panes, Copy, Restore

After this, you’ll go from “I can open a terminal” to “I can keep long-running work alive.” The essence of tmux is simple: your terminal never clocks out. The biggest pitfall is also simple: closing a window is not the same as ending a session. Once you understand detach/attach, you’re halfway there.

This is a full, step-by-step tutorial with config, recovery, sync input, troubleshooting, and a lot of diagrams.

0. Install tmux

Goal: Install tmux and verify the version.

Commands:

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y tmux

CentOS/Rocky:

sudo yum install -y tmux

Arch:

sudo pacman -S tmux

Windows (recommended: WSL2):

wsl --install

Then install tmux inside WSL with apt.

You should see:

tmux -V

Something like tmux 3.x.

If it fails:

• command not found: use the package manager for your OS (or inside WSL).
• permission denied: use an admin account or ask for sudo.

1. Remember these three: session, window, pane

Goal: Understand the three layers so you don’t mix “window” and “session.”

• Session: the big container, usually one per project.
• Window: tabs inside a session.
• Pane: split areas inside a window.

2. Start your first session

Goal: Create a session and enter tmux.

Command:

tmux new -s work

You should see:

• a new terminal screen
• a status bar at the bottom

If it fails:

• session exists: use tmux attach -t work.

3. Detach / attach (the core habit)

Goal: Keep your session running in the background.

Actions:

• Detach (leave running): Ctrl+b then d
• List sessions:

tmux ls

• Reattach:

tmux attach -t work

You should see:

• On detach: [detached (from session work)]
• tmux ls lists the session

If it fails:

• no sessions: create one with tmux new -s work.

4. Windows: think of browser tabs

Goal: Split tasks into separate windows.

Actions:

• New window: C-b c
• Window list: C-b w
• Next/prev window: C-b n / C-b p
• Rename window: C-b ,

Command form:

tmux new-window -n editor

You should see:

• Window list changes in the status bar

If it fails:

• No response: hit C-b ? to see the current keymap.

5. Panes: split one window into multiple views

Goal: Run a server and watch logs in the same window.

Actions:

• Vertical split: C-b %
• Horizontal split: C-b "
• Switch panes: C-b o or C-b Arrow
• Close pane: run exit or C-d

Command form:

tmux split-window -h

You should see:

• One window split into multiple regions

If it fails:

• Too small: enter C-b : resize-pane -L 10 to resize.

6. Prefix key basics

Goal: Understand why tmux needs C-b first.

All tmux commands require a prefix key. The default prefix is C-b (Ctrl + b). After the prefix, tmux waits for the next key to decide which command to run.

List current prefix bindings:

tmux lsk -Tprefix -N

7. Copy mode and scrollback

Goal: Scroll history and copy text inside tmux.

Actions:

• Enter copy mode: C-b [
• Move cursor: Arrow keys / PageUp / PageDown
• Start selection: Space
• Copy and exit: Enter
• Paste: C-b ]

You should see:

• cursor moves in copy mode
• selected region highlighted

If it fails:

• Your keymap may be vi-style; run tmux list-keys -Tcopy-mode to confirm.

8. Mouse support (recommended)

Goal: Scroll with the mouse wheel and click to focus panes.

Action: Add to ~/.tmux.conf:

set -g mouse on

Reload config:

tmux source-file ~/.tmux.conf

You should see:

• wheel scroll works
• click switches panes

If it fails:

• ensure you are inside tmux: [ -n "$TMUX" ] && echo inside tmux

9. Session management with commands

Goal: Control sessions precisely.

Actions:

tmux ls

tmux attach -t work

tmux rename-session -t work ops

Or create-or-attach in one go:

tmux new -As work

You should see:

• sessions listed by tmux ls
• name changes after rename

If it fails:

• name conflict: run tmux ls to confirm.

10. Sync input across panes

Goal: Broadcast one command to all panes.

Action:

• Turn on: C-b : then setw -g synchronize-panes on
• Turn off: C-b : then setw -g synchronize-panes off

You should see:

• the same command appears in multiple panes

If it fails:

• make sure your window actually has multiple panes.

11. Config file basics

Goal: Make tmux fit your habits.

Action: Create ~/.tmux.conf with:

# enable mouse
set -g mouse on

# bigger scrollback
set -g history-limit 100000

# change prefix to C-a (optional)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# vi-style copy mode (optional)
setw -g mode-keys vi

# reload quickly
bind r source-file ~/.tmux.conf \; display-message "tmux reloaded"

Reload config:

tmux source-file ~/.tmux.conf

You should see:

• status message “tmux reloaded”

If it fails:

• check with tmux show -g history-limit.

12. Advanced: multi-client attachment

Goal: Two devices viewing the same session.

Action: On another machine:

tmux attach -t work

You should see:

• both terminals update in sync

If it fails:

• use tmux attach -d -t work to take over.

13. Advanced: session restore

Goal: Restore layouts after reboot.

Action: Use TPM + tmux-resurrect/continuum.

1. Install TPM:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

2. In ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'

3. Press C-b I inside tmux to install plugins.

You should see:

• install messages in the status line
• sessions can be restored after reboot

If it fails:

• verify ~/.tmux/plugins/tpm exists.

14. Shortcut cheat sheet

15. Troubleshooting checklist

1. Hotkeys do nothing: press C-b first, then the key.
2. Copy mode feels wrong: check if you set mode-keys vi.
3. Mouse wheel doesn’t scroll: enable set -g mouse on and reload.
4. Pane too small: use resize-pane or split into multiple windows.
5. Session disappeared: avoid kill-session or kill-server by mistake.
6. WSL scroll issues: update Windows Terminal/WSL or enable mouse.

If you only remember one sentence: tmux is a persistent session manager. Once your sessions live inside tmux, your work no longer depends on the current terminal window.