Quick Start Guide

Get up and running with tmux in 5 minutes. Learn sessions, windows, panes, and essential keyboard shortcuts.

Your First tmux Session

Let’s get you productive with tmux quickly. This guide covers the essential concepts and commands you’ll use daily.

1. Start tmux

   Open your terminal and start your first tmux session:

   tmux
   

   You’ll see a new shell prompt with a green status bar at the bottom showing:

   • [0] - session name
   • 0:bash* - window number and name
   • Your hostname and time on the right
2. Understand the prefix key

   All tmux commands start with a prefix key: C-b (Ctrl-b)

   Press Ctrl and b together, release both keys, then press the command key. For example, C-b c means: press Ctrl-b, release, then press c.

   The prefix key tells tmux: “I’m about to give you a command, not the shell.”

3. Create a new window

   Press C-b c to create a new window.

   Notice the status bar now shows:

   [0] 0:bash- 1:bash*
   

   The * indicates your current window. The - marks the previous window.

4. Navigate between windows

   Try these navigation commands:

   • C-b n - next window
   • C-b p - previous window
   • C-b 0 - switch to window 0
   • C-b 1 - switch to window 1
   • C-b l - toggle between current and last window
5. Split into panes

   Now let’s split a window into multiple panes:

   • C-b % - split vertically (left and right)
   • C-b " - split horizontally (top and bottom)

   Each pane is an independent terminal.

6. Navigate between panes

   Move between panes:

   • C-b o - cycle to next pane
   • C-b ↑ - move to pane above
   • C-b ↓ - move to pane below
   • C-b ← - move to pane on left
   • C-b → - move to pane on right
   • C-b ; - move to previously active pane
7. Detach from session

   Press C-b d to detach from the session.

   You’ll see a message:

   [detached (from session 0)]
   

   Your session is still running in the background! All your windows and panes are preserved.

8. Reattach to session

   Return to your session with:

   tmux attach
   

   Everything is exactly as you left it.

Essential Commands Reference

Session Management

Create new session

# Default session (numbered)
tmux

# Named session
tmux new -s mysession

# Named session with window name
tmux new -s mysession -n mywindow

Window Management

Key Binding	Action
C-b c	Create new window
C-b ,	Rename current window
C-b &	Kill current window (with confirmation)
C-b n	Next window
C-b p	Previous window
C-b 0-9	Switch to window by number
C-b l	Switch to last active window
C-b w	Interactive window list
C-b f	Find window by name
C-b .	Move window to different index

Pane Management

Key Binding	Action
C-b %	Split pane vertically
C-b "	Split pane horizontally
C-b x	Kill current pane (with confirmation)
C-b o	Move to next pane
C-b ;	Move to previously active pane
C-b ↑↓←→	Move to pane in direction
C-b {	Swap with previous pane
C-b }	Swap with next pane
C-b z	Toggle pane zoom (fullscreen)
C-b !	Break pane into new window
C-b q	Show pane numbers

Pane Resizing

Key Binding	Action
C-b C-↑	Resize pane up by 1 cell
C-b C-↓	Resize pane down by 1 cell
C-b C-←	Resize pane left by 1 cell
C-b C-→	Resize pane right by 1 cell
C-b M-↑	Resize pane up by 5 cells
C-b M-↓	Resize pane down by 5 cells
C-b M-←	Resize pane left by 5 cells
C-b M-→	Resize pane right by 5 cells
C-b M-1 to M-7	Apply preset layouts
C-b Space	Cycle through preset layouts

Copy Mode and Scrollback

1. Enter copy mode

   Press C-b [ to enter copy mode and scroll through history.

   You’ll see [0/0] in the top-right corner showing your position in history.

2. Navigate in copy mode

   Emacs mode (default):

   • Arrow keys - move cursor
   • C-Space - begin selection
   • M-w - copy selection
   • C-g - exit copy mode

   Vi mode (if set -g mode-keys vi in config):

   • h/j/k/l - move cursor
   • Space - begin selection
   • Enter - copy selection
   • q - exit copy mode
3. Paste

   Press C-b ] to paste the most recently copied text.

Use Page Up as a shortcut to enter copy mode and scroll up one page immediately.

Other Useful Commands

Key Binding	Action
C-b ?	List all key bindings
C-b :	Enter command prompt
C-b t	Show clock
C-b i	Display window information
C-b ~	Show previous messages
C-b d	Detach from session
C-b D	Choose client to detach
C-b r	Redraw screen
C-b C-b	Send literal C-b to application

Practical Workflow Example

Here’s a common development workflow:

1. Create a development session

   tmux new -s dev
   
2. Set up your layout

   • Start in your project directory
   • Press C-b % to split vertically
   • In the right pane, press C-b " to split horizontally

   You now have three panes:

   ┌─────────┬─────────┐
   │         │         │
   │  Code   │  Tests  │
   │         ├─────────┤
   │         │  Logs   │
   └─────────┴─────────┘
   
3. Run your development tools

   • Left pane: Open your editor (vim, nano, etc.)
   • Top-right pane: Run your test watcher
   • Bottom-right pane: Tail your application logs
4. Detach when done

   Press C-b d to detach. Your session keeps running.

5. Return later

   tmux attach -t dev
   

   Everything is still running!

Remote Development Workflow

One of tmux’s most powerful features is persistence over SSH:

1. SSH to remote server

   ssh user@remote-server
   
2. Start or attach to tmux

   # First time: create session
   tmux new -s work
   
   # Later: reattach to existing session
   tmux attach -t work
   
3. Do your work

   Start long-running builds, tests, or processes.

4. Disconnect safely

   Press C-b d to detach, then exit SSH:

   exit
   

   Your tmux session keeps running on the server!

5. Reconnect anytime

   ssh user@remote-server
   tmux attach -t work
   

   Pick up exactly where you left off.

If your SSH connection drops unexpectedly, tmux automatically detaches. Your session and all running processes continue uninterrupted.

Basic Configuration

Create ~/.tmux.conf to customize tmux:

# Change prefix from C-b to C-a (like screen)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Increase scrollback buffer
set -g history-limit 10000

# Start window numbering at 1 instead of 0
set -g base-index 1
set -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Improve colors
set -g default-terminal "tmux-256color"

# Split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# Reload config file
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Vi mode for copy
set -g mode-keys vi

After creating or editing the config:

# Load configuration in running session
C-b : source-file ~/.tmux.conf

# Or restart tmux
tmux kill-server
tmux

Common Patterns

Create a session with multiple windows

# Create session with specific layout
tmux new-session -d -s myproject -n editor
tmux send-keys -t myproject:editor 'cd ~/myproject && vim' C-m

tmux new-window -t myproject -n tests
tmux send-keys -t myproject:tests 'cd ~/myproject && npm test' C-m

tmux new-window -t myproject -n server  
tmux send-keys -t myproject:server 'cd ~/myproject && npm start' C-m

# Attach to the session
tmux attach -t myproject

Split window with commands

# From shell: create session with splits
tmux new-session -d -s dev 'vim'
tmux split-window -h -t dev 'npm test'
tmux split-window -v -t dev 'npm start'
tmux attach -t dev

Share a session with another user

# User 1: Create named session
tmux new -s pair

# User 2: Attach to same session
tmux attach -t pair

Both users need access to the same server and tmux socket. This is useful for pair programming or collaborative debugging.

Troubleshooting

tmux colors look wrong

Add to your shell configuration (.bashrc, .zshrc):

export TERM=xterm-256color

And in ~/.tmux.conf:

set -g default-terminal "tmux-256color"

Can't scroll with mouse wheel

Enable mouse support in ~/.tmux.conf:

set -g mouse on

Then reload config: C-b : source-file ~/.tmux.conf

Accidentally detached, how to reattach?

# List sessions
tmux ls

# Attach to last session
tmux attach

# Attach to specific session
tmux attach -t session-name

Want to close everything and start fresh

# Kill all tmux sessions and server
tmux kill-server

# Start new session
tmux

Next Steps

Key Bindings

Press C-b ? inside tmux to see all default key bindings, or explore customization options.

Configuration

Learn advanced configuration options in ~/.tmux.conf including status bar customization, custom key bindings, and hooks.

Command Reference

Read the manual page (man tmux) for complete command documentation and options.

Community Resources

Join the tmux community at https://github.com/tmux/tmux for plugins, themes, and support.

The quickest way to learn is to practice! Try using tmux for your next project and the key bindings will become second nature.