Introduction: What tmux Is and Why You'll Keep Using It | tmux Tutorial

This chapter gets you from "I don't have tmux" to "I started a session, detached without panic, and reattached from a different terminal".

What tmux Is

tmux is a terminal multiplexer. It sits between your terminal emulator and your shell, and it gives you three things your shell alone can't:

Persistence. Your shells keep running when you close the terminal or lose an SSH connection. You reconnect and they are exactly where you left them
Layout. Split a window into multiple shells, arranged how you like, without opening new terminals
Scripting. A session is a thing you can script into existence. One command can start your entire dev environment

If you've ever been ten minutes into a long operation over SSH and watched your WiFi drop, you already understand half of why tmux exists.

A tiny bit of history

tmux was written in 2007 as a BSD-licensed alternative to GNU Screen. It replaced Screen for most people because it has a more regular command language, better defaults, and cleaner internals. Screen is still around; tmux is what gets recommended.

Installing

Check if tmux is already installed:

tmux -V

Anything 2.9 or newer is fine. 3.2+ is better. If not:

# macOS with Homebrew
brew install tmux

# Debian, Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

# Windows: tmux needs WSL. Install Ubuntu on WSL, then apt install tmux

Older distros ship ancient tmux. If tmux -V shows 2.x, some features in this tutorial won't exist. Build from source or use Homebrew on macOS / Linuxbrew on Linux to get current.

Your First Session

Run:

tmux

Your terminal clears, a green bar appears at the bottom, and you're back at a shell prompt. That's tmux. You are now inside a session.

Try a command:

ls

Normal shell. Nothing exotic. The magic is that this shell is not really attached to your terminal any more. It belongs to the tmux server. The terminal is just a window onto it.

The Prefix Key

Every tmux command starts with a prefix key. By default, Ctrl-b. You press the prefix, let go, then press a command key.

Try it. Press Ctrl-b, release, then ?:

Ctrl-b ?

A scrollable list of every key binding appears. Press q to close it.

In this tutorial, <prefix> means "press Ctrl-b and release":

<prefix> ?         show help
<prefix> d         detach
<prefix> c         new window
<prefix> "         split horizontally

Most tmux users rebind the prefix to something more comfortable. Ctrl-a is common (it matches Screen). Ctrl-space is another favourite. We cover rebinding in chapter 7. For now, use Ctrl-b.

Detaching

Here is the feature that sells most people on tmux:

<prefix> d

Your tmux session vanishes. You're back in your regular shell, with a message like:

[detached (from session 0)]

The session is still running. Your shells are still alive. They just don't have a terminal attached.

Close the terminal. Open a new one. Run:

tmux attach

You're back inside the session, cursor where you left it, scrollback intact.

That is the core of tmux. Everything else is decoration.

Listing Sessions

From outside tmux (any regular shell):

tmux ls

Or equivalently:

tmux list-sessions

You'll see something like:

0: 1 windows (created Sun Apr 20 10:45:11 2026)

Session 0 has one window, created at that timestamp. Session IDs are numeric unless you name them.

Attaching

tmux attach           # attach to the most recent session
tmux a                # alias
tmux attach -t 0      # attach to session 0
tmux a -t work        # attach to session named "work"

If you try to attach with no running sessions, tmux says so:

no server running on /tmp/tmux-1000/default

Just run tmux again to start one.

Killing Sessions

Leave the session behind (it keeps running):

<prefix> d

End the session (shells inside will be killed):

tmux kill-session -t 0
tmux kill-session -t work

Or from inside a session, exit every shell until the session has no windows. When the last shell exits, the session dies.

Nuke everything:

tmux kill-server

That shuts down the tmux server and every session with it. Use when you want to start clean.

A Realistic First Session

tmux new -s work            # start a named session
# ... do stuff, run commands, open vim
<prefix> d                   # detach. session "work" keeps running

# close the terminal. open a new one. open an SSH connection. whatever

tmux a -t work              # back where you were

Do that a few times. When reattaching feels automatic, you've got the core.

The Help Binding

<prefix> ? is worth memorising immediately. It shows every binding with a search field. Type to filter, q to exit. If you forget any command in this tutorial, <prefix> ? has it.

For a text reference:

man tmux

The man page is long. It is also authoritative and well-written. Skim it once in the first week.

Common Pitfalls

"I pressed Ctrl-b and nothing happened." You pressed it inside an app that also uses Ctrl-b (less, emacs). Leave the app, or bind the prefix to something else (chapter 7).

"My terminal caught Ctrl-b before tmux." Unusual. Check your terminal's key bindings; some let you disable a shortcut conflict.

"tmux ls says no server running after I detached." The server quits when the last session ends. If you ran exit instead of detaching, the session is gone. <prefix> d detaches. Typing exit in the last shell closes the window, closes the session, closes the server.

"I rebooted. My sessions are gone." tmux sessions live in memory. A reboot kills them. Plugins like tmux-resurrect save state across reboots (chapter 10).

"Colours look wrong." Set TERM=screen-256color before running tmux, or add set -g default-terminal "tmux-256color" to .tmux.conf. More on this in chapter 7.

Next Steps

Continue to 02-sessions.md for the full set of commands around sessions.