How Do I Use Tmux?

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

This guided tutorial teaches by doing, with step-by-step instructions to learn 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, ensure you have:

• 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 based on 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 doesn’t run natively on Windows; use Windows Subsystem for Linux (WSL) to run it. WSL provides a Linux environment within Windows, enabling you to run tools like tmux as on Linux servers.

Prerequisites:

1. Install WSL if you haven’t already. See the Microsoft WSL documentation for installation 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. You’ll see a status bar at the bottom showing session information.

Create a named session:

tmux new -s mysession

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

To completely exit tmux when you’re done, type exit in the last pane or window (or press Ctrl-d). When the last window closes, the session ends.

Understanding Tmux Basics

Now that you’ve started your first tmux session, let’s look at how tmux keybindings work.

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

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

You can think of tmux’s structure like this: one server manages multiple sessions; each session can have multiple windows; each window can have 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 continues running in the background. Close your terminal window; the session persists.

Listing Sessions

List all active sessions:

tmux ls

You’ll see output like:

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

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 are like browser tabs within a session. Each window can contain multiple panes.

Creating a New Window

Create a new window:

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

The status bar shows window numbers. You’ll see 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 let you view multiple terminals side-by-side in one window. Think of panes as split screens within a single window.

The diagram below shows one window with a top row split into two panes and a full-width bottom pane. Here’s a visual example:

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

Creating Horizontal Panes

Split the window horizontally (top and bottom):

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

You’ll see two panes stacked vertically.

Creating Vertical Panes

Split the window vertically (left and right):

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

You’ll see two panes side-by-side.

Navigating Between Panes

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 persistent session:

ssh user@server
tmux new -s dev

If your SSH connection drops, the tmux session keeps running on the server. When you reconnect and run tmux attach -t dev, you pick up exactly where you left off:

ssh user@server
tmux attach -t dev

Multi-Pane Development Setup

Create a three-pane setup for monitoring logs, running tests, and executing 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.

You can use this same navigation pattern (Ctrl-b then arrow keys) in any tmux window, not just this layout.

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

At this point, you’ve used tmux for remote dev, multi-pane work, project separation, and long-running tasks. These are the most common real-world tmux use cases.

Copy Mode

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

Entering Copy Mode

Enter copy mode:

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

You’re now in copy mode. Use arrow keys to navigate; if your tmux uses vi-style keys, try h, j, k, l. If those don’t work, 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 don’t behave as described, your tmux config or Linux distro may use different copy-mode bindings. Some distros ship tmux with default bindings, or your dotfiles may redefine keys. If keys behave differently, nothing is broken; your environment has custom defaults. Check ~/.tmux.conf or the tmux manual for 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 initially and review it later when you’re comfortable with the default keys. Notable when switching windows/panes often or using 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’re ending unexpectedly:

Check for accidental session kills:

• Verify you’re not pressing Ctrl-b then & (which kills the current window).
• Check if you’re 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 holding sessions and windows. tmux ls asks this server which sessions are active.

As described earlier, tmux runs a background server that manages sessions, with each session containing windows and multiple panes.

When no server is running, you might see:

failed to connect to server

If you see failed to connect to server, tmux has no running sessions. Create a new one with tmux new -s dev.

Check for tmux errors:

On Linux and macOS, tmux doesn’t run as a system service by default. Instead, check the 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 an error like tmux: server exited unexpectedly in your terminal. After seeing this error, try starting a new session with tmux new -s test. If it fails again with the same error, consider searching for or reporting it on the tmux GitHub issues.

If you suspect the tmux config causes a crash, try starting with a minimal config:

tmux -f /dev/null new -s test

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

Panes Not Resizing

If pane resizing doesn’t work:

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 don’t work, 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 and disable conflicts.

Can’t See Status Bar

The status bar should appear at the bottom. 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, here’s what to 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 focused task recipes, see the tmux how-to guides when available, and for complete command listings, rely on the tmux manual. This tutorial covers core workflows; use it alongside the manual.

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

Your terminal work is now more reliable and organized.

Quick Reference

Use this quick reference as a cheat sheet while practicing the steps above. These tables are intended to support the tutorial, 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.

If you use a screen reader, these tables summarize each command described earlier by action and shortcut. The tables below list the commands you’ve learned so far:

Session Commands

Window Commands

Pane Commands

Copy Mode Shortcuts

References

• tmux Official Website - Main website with features, documentation, and download information
• tmux Manual Page - Comprehensive command reference and configuration guide
• tmux GitHub Repository - Open-source codebase and community contributions
• What Is Tmux? - Explanation of what tmux is and why it matters

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

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