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?]({{< ref "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:

```bash
brew install tmux
```

Verify installation:

```bash
tmux -V
```

### Linux

Most distributions include tmux in their repositories.

**Ubuntu/Debian:**

```bash
sudo apt update
sudo apt install tmux
```

**Fedora/RHEL:**

```bash
sudo dnf install tmux
```

**Arch Linux:**

```bash
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](https://learn.microsoft.com/en-us/windows/wsl/install) 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:**

```bash
sudo apt update
sudo apt install tmux
```

**Fedora/RHEL in WSL:**

```bash
sudo dnf install tmux
```

Verify installation:

```bash
tmux -V
```

## Creating Your First Session

Start a new tmux session:

```bash
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:

```bash
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:

```bash
tmux ls
```

You'll see output like:

```text
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:

```bash
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:

```bash
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:

```text
┌─────────────────┬─────────────────┐
│                 │                 │
│   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:

```bash
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:

```bash
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:

```bash
tmux new -s frontend
tmux new -s backend
tmux new -s deployment
```

Switch between projects:

```bash
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:

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

Check progress later:

```bash
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:

```bash
touch ~/.tmux.conf
```

Add common customizations:

```bash
# 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:**

```bash
tmux ls
```

Expected output shows active sessions:

```text
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:

```text
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:

```bash
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

| Action | Command |
|-------|---------|
| Create new session | `tmux new -s name` |
| List sessions | `tmux ls` |
| Attach to session | `tmux attach -t name` |
| Kill session | `tmux kill-session -t name` |
| Detach from session | `Ctrl-b` then `d` |

### Window Commands

| Action | Shortcut |
|-------|----------|
| Create new window | `Ctrl-b` then `c` |
| Next window | `Ctrl-b` then `n` |
| Previous window | `Ctrl-b` then `p` |
| Switch to window number | `Ctrl-b` then `0-9` |
| Rename window | `Ctrl-b` then `,` |
| Close window | `Ctrl-b` then `&` |

### Pane Commands

| Action | Shortcut |
|-------|----------|
| Split horizontally | `Ctrl-b` then `"` |
| Split vertically | `Ctrl-b` then `%` |
| Next pane | `Ctrl-b` then `o` |
| Previous pane | `Ctrl-b` then `;` |
| Navigate with arrows | `Ctrl-b` then `←→↑↓` |
| Resize pane | `Ctrl-b` then `Ctrl-←→↑↓` |
| Close pane | `Ctrl-b` then `x` |

### Copy Mode Shortcuts

| Action | Shortcut |
|-------|----------|
| Enter copy mode | `Ctrl-b` then `[` |
| Start selection | `Space` |
| Copy selection | `Enter` |
| Paste | `Ctrl-b` then `]` |

## References

* [tmux Official Website](https://tmux.github.io/) - Main website with features, documentation, and download information
* [tmux Manual Page](https://man.openbsd.org/tmux) - Comprehensive command reference and configuration guide
* [tmux GitHub Repository](https://github.com/tmux/tmux) - Open-source codebase and community contributions
* [What Is Tmux?]({{< ref "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.