You want to start using tmux but find the commands overwhelming, the key bindings cryptic, and the learning curve steep.

This tutorial teaches tmux through hands-on practice. By the end, you’ll create sessions, split panes, and manage multiple terminal windows confidently.

If you’re new to tmux, start with What Is Tmux? to understand what it does and why it matters.

Prerequisites

Before starting, you need:

  • A terminal emulator installed (such as Terminal on macOS, GNOME Terminal on Linux, or Windows Terminal with WSL on Windows).
  • Basic command-line familiarity (navigating directories, running commands).
  • tmux installed (see the installation section).

Installing Tmux

Install tmux for your operating system.

macOS

Use Homebrew:

brew install tmux

Verify installation:

tmux -V

Linux

Most distributions include tmux in their repositories.

Ubuntu/Debian:

sudo apt update
sudo apt install tmux

Fedora/RHEL:

sudo dnf install tmux

Arch Linux:

sudo pacman -S tmux

Windows

tmux requires Linux; on Windows, use Windows Subsystem for Linux (WSL). WSL provides a Linux environment within Windows, letting you run tmux as you would on a Linux server.

Prerequisites:

  1. Install WSL. See the Microsoft WSL documentation for instructions.
  2. Open your WSL terminal (Ubuntu, Debian, or your preferred Linux distribution).

Installation:

Once WSL is set up, install tmux using your Linux distribution’s package manager:

Ubuntu/Debian in WSL:

sudo apt update
sudo apt install tmux

Fedora/RHEL in WSL:

sudo dnf install tmux

Verify installation:

tmux -V

Creating Your First Session

Start a new tmux session:

tmux

This creates an unnamed session and attaches you to it. A status bar at the bottom shows session information.

Create a named session:

tmux new -s mysession

Replace mysession with your preferred name. Named sessions help organize multiple projects.

To exit tmux, type exit in the last pane or window (or press Ctrl-d). The session ends when the last window closes.

Understanding Tmux Basics

Now that you’ve started your first tmux session, learn how keybindings work.

tmux uses a prefix key to trigger commands. The default prefix is Ctrl-b. Press Ctrl-b, release both keys, then press the command key.

Think of Ctrl-b as telling tmux, “the next key is a tmux command.”

tmux’s structure works like this: one server manages multiple sessions; each session holds multiple windows; each window holds multiple panes.

Essential Session Commands

Detaching from a Session

Detach without ending the session:

  1. Press Ctrl-b.
  2. Release both keys.
  3. Press d.

Your session keeps running in the background. Even if you close your terminal window, the session persists.

Listing Sessions

List all active sessions from the command line:

tmux ls

Output looks like:

mysession: 1 windows (created Sun Nov 24 10:30:00 2025)
another: 1 windows (created Sun Nov 24 11:00:00 2025)

From inside a tmux session, open the interactive session list:

  1. Press Ctrl-b.
  2. Press s.

Navigate with the arrow keys and press Enter to switch to the selected session.

Switching Between Sessions

Cycle between sessions without opening the interactive list:

  • Next session: Ctrl-b then ).
  • Previous session: Ctrl-b then (.

Attaching to a Session

Attach to an existing session:

tmux attach -t mysession

Replace mysession with your session name. Use tmux a -t mysession as a shorter alias.

Killing a Session

End a session permanently:

tmux kill-session -t mysession

Or from inside tmux:

  1. Press Ctrl-b.
  2. Press &.
  3. Confirm with y.

Working with tmux Windows

tmux windows work like browser tabs within a session. Each window holds multiple panes.

Creating a New Window

Create a new window:

  1. Press Ctrl-b.
  2. Press c.

The status bar shows window numbers: 0:bash, 1:bash, etc.

Switching Between Windows

Navigate windows:

  • Next window: Ctrl-b then n.
  • Previous window: Ctrl-b then p.
  • Specific window: Ctrl-b then the window number (e.g., Ctrl-b then 0 for window 0).

Renaming a Window

Rename the current window:

  1. Press Ctrl-b.
  2. Press ,.
  3. Type the new name.
  4. Press Enter.

Closing a Window

Close the current window:

  1. Press Ctrl-b.
  2. Press &.
  3. Confirm with y.

Or type exit in the terminal.

Splitting Panes

Panes split a single window into multiple terminals. The diagram below shows one window with a top row split into two panes and a full-width bottom pane:

┌─────────────────┬─────────────────┐
│                 │                 │
│   Top Pane      │   Top Right     │
│                 │                 │
├─────────────────┴─────────────────┤
│                                   │
│         Bottom Pane               │
│                                   │
└───────────────────────────────────┘

Creating Horizontal Panes

Split the window horizontally (top and bottom):

  1. Press Ctrl-b.
  2. Press ".

Two panes appear stacked vertically.

Creating Vertical Panes

Split the window vertically (left and right):

  1. Press Ctrl-b.
  2. Press %.

Two panes appear side-by-side.

Switch between panes:

  • Next pane: Ctrl-b then o.
  • Previous pane: Ctrl-b then ;.
  • Directional navigation: Ctrl-b then arrow keys (←, →, ↑, ↓).

Resizing Panes

Resize the current pane using Ctrl-b then Ctrl-←/→/↑/↓:

  • Ctrl-b then Ctrl-← to shrink left.
  • Ctrl-b then Ctrl-→ to expand right.
  • Ctrl-b then Ctrl-↑ to expand up.
  • Ctrl-b then Ctrl-↓ to shrink down.

Closing Panes

Close the current pane:

Type exit in the pane’s terminal, or:

  1. Press Ctrl-b.
  2. Press x.
  3. Confirm with y.

Common Workflows

Remote Server Development

Connect to a remote server and start a session:

ssh user@server
tmux new -s dev

If your SSH connection drops, the tmux session keeps running on the server. Reconnect and reattach to pick up where you left off:

ssh user@server
tmux attach -t dev

Multi-Pane Development Setup

Create a three-pane setup to monitor logs, run tests, and execute commands:

  1. Start tmux: tmux new -s project.
  2. Split horizontally: Ctrl-b then ".
  3. Move to the bottom pane: Ctrl-b then o.
  4. Split the bottom pane vertically: Ctrl-b then %.
  5. Navigate panes: Ctrl-b then arrow keys.

This navigation pattern (Ctrl-b then arrow keys) works in any tmux window.

You now have three panes:

  • Top: Main terminal.
  • Bottom-left: Logs or tests.
  • Bottom-right: Commands or database queries.

Project Organization

Create separate sessions for different projects:

tmux new -s frontend
tmux new -s backend
tmux new -s deployment

Switch between projects:

tmux attach -t frontend
# Work on frontend
# Detach with Ctrl-b d
tmux attach -t backend
# Work on backend

Long-Running Processes

Start a long-running process in tmux:

tmux new -s migration
# Run your long command
./long-running-script.sh
# Detach with Ctrl-b d

Check progress later:

tmux attach -t migration

You’ve now practiced the most common tmux workflows: remote development, multi-pane layouts, project separation, and long-running tasks.

Copy Mode

Copy mode lets you scroll through terminal history and copy text within tmux.

Entering Copy Mode

Enter copy mode:

  1. Press Ctrl-b.
  2. Press [.

You are now in copy mode. Navigate with arrow keys; if your tmux uses vi-style keys, use h, j, k, l. Otherwise, use arrow keys or enable vi mode in your config.

Copying Text

  1. Navigate to the start of the text you want to copy.
  2. Press Space to start selection.
  3. Move to the end of the text.
  4. Press Enter to copy.

If Space and Enter behave differently, your tmux config or Linux distro uses different copy-mode bindings. Some distros ship custom defaults, or your dotfiles redefine keys. Check ~/.tmux.conf or the tmux manual for your key mappings.

Pasting Text

Paste copied text:

  1. Press Ctrl-b.
  2. Press ].

Basic Configuration

This section is optional. If you’re new to tmux, skip it and return when you’re comfortable with the default keys. Configuration pays off most when you switch windows and panes often or use tmux all day.

Create a configuration file to customize tmux:

touch ~/.tmux.conf

Add common customizations:

# Set prefix to Ctrl-a (easier to reach)
# Changing the prefix to Ctrl-a keeps your hands on the home row, which many terminal users prefer
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Enable mouse support
set -g mouse on

# Start windows and panes at 1, not 0
# Starting windows and panes at 1 instead of 0 feels more natural to many users when switching by number
set -g base-index 1
setw -g pane-base-index 1

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

Reload your configuration:

  1. Press your tmux prefix (Ctrl-b by default, or Ctrl-a if you changed it above).
  2. Press : to enter command mode.
  3. Type source-file ~/.tmux.conf.
  4. Press Enter.

Or restart tmux to apply changes.

Troubleshooting Common Issues

Can’t Detach from Session

If Ctrl-b d doesn’t work:

  • Ensure you press Ctrl-b, release both keys, then press d.
  • Check if another program is intercepting Ctrl-b.
  • Try Ctrl-b then : to enter command mode, then type detach.

Session Not Persisting

Sessions persist by default. If they end unexpectedly:

Check for accidental session kills:

  • Verify you’re not pressing Ctrl-b then &, which kills the current window.
  • Verify you’re not typing exit in the terminal, which closes the session.

Verify tmux server status:

tmux ls

Expected output shows active sessions:

dev: 1 windows (created Sun Nov 24 10:30:00 2025)
project: 2 windows (created Sun Nov 24 11:00:00 2025)

tmux runs a background server that holds sessions and windows. tmux ls queries this server for active sessions.

When no server is running, you see:

failed to connect to server

This message means tmux has no running sessions. Create a new one with tmux new -s dev.

Check for tmux errors:

On Linux and macOS, tmux runs as a user process, not a system service. Check your terminal history for shell errors or crashes. If tmux crashes repeatedly, note the error message and search the tmux GitHub issues or documentation.

For example, you might see tmux: server exited unexpectedly in your terminal. Try starting a new session with tmux new -s test. If it fails again with the same error, search for or report it on the tmux GitHub issues.

If you suspect your tmux config causes the crash, start with a minimal config:

tmux -f /dev/null new -s test

If this works but tmux new -s test fails, the problem is in your ~/.tmux.conf.

Panes Not Resizing

If panes do not resize:

Verify the key sequence:

  • Ensure you’re using Ctrl-b then the Ctrl-←/→/↑/↓ keys, just like in the pane resizing section above.
  • Try releasing Ctrl-b completely before pressing Ctrl-arrow.

Use command mode as an alternative:

If key bindings fail, use command mode:

  1. Press Ctrl-b then : to enter command mode.
  2. Type resize-pane -L 5 (shrink left by 5 characters).
  3. Adjust direction: -L (left), -R (right), -U (up), -D (down).
  4. Adjust size: Change 5 to your desired number of characters.

Check terminal emulator conflicts:

Some terminal emulators intercept Ctrl-arrow keys. Check your terminal’s key bindings for conflicts and disable them.

Can’t See Status Bar

The status bar appears at the bottom of the terminal. If missing:

  • Check your configuration file for set -g status on.
  • Verify you’re actually in a tmux session (look for [mysession] in the status bar).

Next Steps

Now that you know tmux basics, explore next:

  • Customize your configuration: Create a .tmux.conf that matches your workflow.
  • Learn advanced features: Scripting, session sharing, and plugins.
  • Practice daily: Use tmux for real work to build muscle memory.
  • Read the full tmux manual (man page): man tmux covers all features and options.

For task recipes, see the tmux how-to guides when available. For complete command listings, consult the tmux manual. This tutorial covers core workflows; use it alongside the manual.

tmux grows more powerful with regular use. Start with simple sessions, then add panes and windows as needed.

Quick Reference

Use this quick reference while practicing the steps above. These tables support the tutorial; they do not replace the tmux manual.

These shortcuts assume the default prefix Ctrl-b. If you changed your prefix (for example, to Ctrl-a in your ~/.tmux.conf), substitute your prefix key wherever you see Ctrl-b.

Session Commands

  • tmux new -s name - Create a new named session
  • tmux ls - List all active sessions
  • tmux attach -t name - Attach to an existing session
  • tmux kill-session -t name - End a session permanently
  • Ctrl-b d - Detach from the current session
  • Ctrl-b s - Open the interactive session list
  • Ctrl-b ) - Switch to the next session
  • Ctrl-b ( - Switch to the previous session

Window Commands

  • Ctrl-b c - Create a new window
  • Ctrl-b n - Move to the next window
  • Ctrl-b p - Move to the previous window
  • Ctrl-b 0-9 - Switch to a specific window by number
  • Ctrl-b , - Rename the current window
  • Ctrl-b & - Close the current window

Pane Commands

  • Ctrl-b “ - Split the window horizontally
  • Ctrl-b % - Split the window vertically
  • Ctrl-b o - Move to the next pane
  • Ctrl-b ; - Move to the previous pane
  • Ctrl-b arrow keys - Navigate panes directionally
  • Ctrl-b Ctrl-arrow keys - Resize the current pane
  • Ctrl-b x - Close the current pane

Copy Mode Commands

  • Ctrl-b [ - Enter copy mode
  • Space - Start text selection
  • Enter - Copy the selection
  • Ctrl-b ] - Paste copied text

References

Commands in this tutorial were verified with tmux 3.x. Run tmux -V to check your version.

If something in this tutorial doesn’t work as described, let me know so I can fix it.