Skip to content

Introduction to tmux

Overview

Questions - What is tmux and why should I use it on HPC clusters? - How can I keep my terminal sessions persistent?

Objectives - Understand what tmux is and its benefits for HPC workflows - Learn essential tmux commands for managing sessions - Use tmux with Slurm for persistent interactive compute sessions

What is tmux?

tmux (terminal multiplexer) is a tool that lets you create and manage persistent terminal sessions. For researchers working on HPC clusters, tmux is essential because it keeps your terminal sessions alive even when your SSH connection drops.

Common scenario without tmux

You're running an interactive analysis on the cluster and your laptop battery dies. Your SSH connection is lost, and all your work—running processes, command history, environment setup—is gone.

With tmux

You're running the same analysis inside a tmux session. Your laptop battery dies, but when you reconnect via SSH and reattach to your tmux session, everything is exactly as you left it. Your processes are still running.

Quick Start: Essential Commands

Starting tmux

code

Create a new tmux session: 

# Start a new session
tmux

# Or start with a specific name (recommended)
tmux new -s mywork

The Prefix Key

Understanding the Prefix Key

All tmux commands start with a prefix key: Ctrl+B

You press Ctrl+B, release, then press the next key. This is how tmux distinguishes its commands from regular terminal input.

Detaching and Reattaching

Detach from a session (keeps it running in the background):

Ctrl+B then D

List all sessions:

code

tmux ls

Reattach to a session:

code

# Reattach to the most recent session
tmux attach

# Or attach to a specific session by name
tmux attach -t mywork

Basic Workflow Example

code

# On cluster login node: Start tmux
tmux new -s analysis

# Do some work...
cd /path/to/project
source activate myenv
python script.py

# Need to disconnect? Detach from tmux
# Press: Ctrl+b, then d

# Connection drops or you close laptop
# Later, reconnect via SSH
ssh cluster.university.edu

# Resume your session
tmux ls
tmux attach -t analysis

# You're back! Everything still running

Working with Panes

tmux lets you split your terminal window into multiple panes to view and work in multiple areas simultaneously.

Splitting Panes

Split Commands

Split horizontally (one pane above, one below): Ctrl+B then ++shift+"++

Split vertically (one pane left, one right): Ctrl+B then Shift+5

Move between panes:

Ctrl+B then ++arrow-keys++

Closing Panes

code

Close current pane: 

exit
Or press Ctrl+D

Visual Example

┌─────────────────────────────┐
│                             │
│      Top pane               │
│      (running jupyter)      │
│                             │
├─────────────┬───────────────┤
│             │               │
│  Left pane  │  Right pane   │
│  (editor)   │  (monitoring) │
│             │               │
└─────────────┴───────────────┘

Practical HPC Example: tmux + Slurm

Here's a complete workflow combining tmux with Slurm for persistent interactive compute sessions:

Step 1: Start tmux on Login Node

code

# SSH to cluster
ssh cluster.university.edu

# Start named tmux session
tmux new -s compute-work

Step 2: Request Interactive Compute Node

Inside your tmux session, request resources via Slurm:

code

# Request interactive compute node
srun --pty --partition=interactive --cpus-per-task=4 --mem=16G --time=02:00:00 bash

# You're now on a compute node!
# Check which node you're on
hostname

Step 3: Run Your Analysis

code

# Activate environment
conda activate myproject

# Run interactive analysis
python my_analysis.py

# Or start Jupyter
jupyter lab --no-browser --port=8888

Step 4: Detach and Disconnect

Your work is running. Now you can safely disconnect:

Ctrl+B then D

code

# Your session is detached
# You can even log out completely
exit

Step 5: Reconnect Later

code

# Reconnect to cluster (minutes, hours, or days later)
ssh cluster.university.edu

# List your sessions
tmux ls
# Output: compute-work: 1 windows (created Mon Nov 13 14:23:45 2023)

# Reattach
tmux attach -t compute-work

# You're back! Your compute job is still running
# Jupyter is still serving
# All your work intact

Why This Matters

  • SSH disconnections don't kill your work - laptop sleep, network issues, closing terminal—all safe
  • Monitor long-running processes - check back anytime to see progress
  • Persistent interactive sessions - maintain your Slurm allocation even when disconnected
  • Multiple views - use panes to watch logs while running commands

Common tmux Commands Reference

Action Command
Start new session tmux or tmux new -s name
Detach session Ctrl+B D
List sessions tmux ls
Attach to session tmux attach -t name
Split horizontal Ctrl+B ++shift+"++
Split vertical Ctrl+B Shift+5
Navigate panes Ctrl+B ++arrow-keys++
Close pane exit or Ctrl+D
Kill session tmux kill-session -t name

Further Learning

Advanced Topics and Customization

For advanced usage, customization, and plugins:

tmux is highly customisable via .tmux.conf. The official documentation has extensive guides on configuring key bindings, colors, status bars, and plugins.

Key Takeaways

  • tmux keeps your terminal sessions alive even when SSH disconnects
  • Essential commands: tmux new -s name, Ctrl+B D (detach), tmux attach -t name
  • Split panes with Ctrl+B ++shift+"++ (horizontal) and Ctrl+B Shift+5 (vertical)
  • Perfect for interactive Slurm jobs - your compute session persists even if you disconnect
  • Use descriptive session names to easily identify and reattach to your work