HOW-TO: Using tmux in Linux for Long-Running Tasks
A practical guide to using tmux for managing long-running tasks in Linux, including downloading large models, with session management, monitoring, and configuration tips.
HOW-TO: Using tmux in Linux for Long-Running Tasks
Overview
tmux is a terminal multiplexer that allows you to:
- Detach and reattach sessions (run tasks while offline)
- Split terminals into multiple panes
- Manage multiple windows within a single session
- Persist processes across SSH disconnections
- Monitor multiple tasks simultaneously
This guide covers practical usage for long-running tasks like downloading large ML models from Hugging Face, training jobs, or system maintenance.
Installation
Ubuntu/Debian
sudo apt update
sudo apt install tmux
tmux --version # Verify installation
macOS
brew install tmux
From Source
git clone https://github.com/tmux/tmux.git
cd tmux
sh autogen.sh
./configure && make
sudo make install
Core Concepts
Sessions
A session is a container for windows and panes. You can detach from a session and reattach later (even after closing your terminal).
Windows
A window is a viewport within a session (like a tab in a browser).
Panes
A pane is a split within a window (allows viewing multiple terminals simultaneously).
Visual Hierarchy:
Session (connection)
āāā Window 1 (tab)
ā āāā Pane A
ā āāā Pane B
āāā Window 2 (tab)
āāā Pane A
Quick Start
Create a New Session
tmux new-session -s my_session
# Shorthand:
tmux new -s my_session
List Active Sessions
tmux list-sessions
# Shorthand:
tmux ls
Attach to a Session
tmux attach-session -t my_session
# Shorthand:
tmux a -t my_session
Kill a Session
tmux kill-session -t my_session
Practical Use Case: Downloading a Large Model
Scenario
Download Qwen3.5-9B from Hugging Face while maintaining session persistence.
Step 1: Create a Dedicated Session
tmux new-session -s model_download
Step 2: Start the Download
# Inside the tmux session
huggingface-cli download Qwen/Qwen3.5-9B \
--repo-type model \
--local-dir ./models/qwen3.5-9b \
--resume-download
Step 3: Detach from Session (Keep Running)
Press: Ctrl + B, then D
Your download continues in the background!
Step 4: Check Status Later
# From terminal (session still running)
tmux attach -t model_download
# Or list all sessions to confirm it's running
tmux ls
Example Output
model_download: 1 windows (created Mon Mar 23 12:16:37 2026)
training_job: 1 windows (created Mon Mar 23 10:45:22 2026)
Essential Key Bindings
Prefix Key: Ctrl + B (followed by another key)
Session Management
| Command | Result |
|---|---|
Ctrl+B, D | Detach from current session |
Ctrl+B, ( | Previous session |
Ctrl+B, ) | Next session |
Ctrl+B, L | Last (previously used) session |
Ctrl+B, S | Choose session (interactive menu) |
Window Management
| Command | Result |
|---|---|
Ctrl+B, C | Create new window |
Ctrl+B, & | Kill current window |
Ctrl+B, N | Next window |
Ctrl+B, P | Previous window |
Ctrl+B, 0-9 | Jump to window by number |
Ctrl+B, , | Rename current window |
Ctrl+B, W | Choose window (interactive menu) |
Pane Management
| Command | Result |
|---|---|
Ctrl+B, " | Split horizontally |
Ctrl+B, % | Split vertically |
Ctrl+B, X | Kill current pane |
Ctrl+B, Arrow Keys | Navigate between panes |
Ctrl+B, O | Cycle through panes |
Ctrl+B, Space | Cycle through layouts |
Ctrl+B, ! | Convert pane to window |
Scrolling & Copying
| Command | Result |
|---|---|
Ctrl+B, [ | Enter copy mode (scroll history) |
Space | Start selection (in copy mode) |
Enter | Copy selection (in copy mode) |
Ctrl+B, ] | Paste |
Practical Workflow: Multi-Task Monitoring
Setup
Monitor a model download, training job, and system metrics simultaneously.
# Create session
tmux new-session -s ml_pipeline -d
# Window 1: Model download
tmux send-keys -t ml_pipeline "huggingface-cli download Qwen/Qwen3.5-9B --repo-type model" Enter
# Window 2: Training (create new window)
tmux new-window -t ml_pipeline
tmux send-keys -t ml_pipeline:1 "python train.py" Enter
# Window 3: System monitoring (create new window)
tmux new-window -t ml_pipeline
tmux send-keys -t ml_pipeline:2 "watch -n 1 nvidia-smi" Enter
# Attach to session
tmux attach -t ml_pipeline
Navigate Between Windows
Ctrl+B, 0 # Window 0 (download)
Ctrl+B, 1 # Window 1 (training)
Ctrl+B, 2 # Window 2 (monitoring)
Ctrl+B, N # Next window
Ctrl+B, P # Previous window
Sending Commands to Sessions
Send Command Without Attaching
# Run command in detached session
tmux send-keys -t session_name "command_here" Enter
# Example: Start download in background
tmux send-keys -t model_download "ollama pull qwen3.5:9b" Enter
Run Script in Detached Session
# Create session, run script, keep window open
tmux new-session -d -s my_script -c ~/scripts
tmux send-keys -t my_script "bash long_task.sh" Enter
Monitoring Long-Running Tasks
Check Session Status
# List sessions with details
tmux list-sessions
# Show all windows in a session
tmux list-windows -t session_name
# Show all panes in a window
tmux list-panes -t session_name:window_number
View Session Contents Without Attaching
# Capture pane output
tmux capture-pane -t session_name -p
# Get last N lines
tmux capture-pane -t session_name -p -S -30
Real-Time Monitoring
# Watch session output in real-time
tmux attach -t session_name -r # Read-only (won't interfere)
# Or attach normally
tmux attach -t session_name
Log Session Output
# Pipe output to file
tmux capture-pane -t session_name -p > session_log.txt
# Or redirect within session
tmux send-keys -t session_name "script > output.log 2>&1" Enter
Configuration: Custom .tmux.conf
Create ~/.tmux.conf to customize tmux behavior.
Basic Configuration
# Set prefix key (optional, default is Ctrl+B)
set-option -g prefix C-a
unbind-key C-b
# Enable mouse support
set -g mouse on
# Increase scrollback history
set -g history-limit 50000
# Start window numbering from 1 (not 0)
set -g base-index 1
set -g pane-base-index 1
# Enable 256 colors
set -g default-terminal "screen-256color"
# Reload configuration
bind r source-file ~/.tmux.conf \; display "Config reloaded!"
# Pane navigation with Ctrl+Arrow
bind -n C-Left select-pane -L
bind -n C-Right select-pane -R
bind -n C-Up select-pane -U
bind -n C-Down select-pane -D
# Window navigation with Alt+Number
bind -n M-1 select-window -t 1
bind -n M-2 select-window -t 2
bind -n M-3 select-window -t 3
Apply Configuration
# Source the file
tmux source-file ~/.tmux.conf
# Or restart tmux for full effect
tmux kill-server # Kill all sessions
tmux # Start fresh
Advanced Techniques
Persistent Sessions Across Reboots
Use tmux-resurrect plugin to save/restore sessions.
Installation
# Install tmux package manager (tpm)
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
# Add to ~/.tmux.conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
# Install plugins
~/.tmux/plugins/tpm/bin/install_plugins
Usage
# Save session state
Ctrl+B, Ctrl+S
# Restore after reboot
Ctrl+B, Ctrl+R
Creating Session Layouts with Script
#!/bin/bash
# setup_ml_session.sh
SESSION="ml_work"
# Kill existing session
tmux kill-session -t $SESSION 2>/dev/null
# Create session with 3 windows
tmux new-session -d -s $SESSION -x 200 -y 50
# Window 0: Main terminal
tmux send-keys -t $SESSION:0 "cd ~/projects/ml_project" Enter
# Window 1: Model download
tmux new-window -t $SESSION -n download
tmux send-keys -t $SESSION:1 "huggingface-cli download Qwen/Qwen3.5-9B --repo-type model" Enter
# Window 2: Training
tmux new-window -t $SESSION -n training
tmux send-keys -t $SESSION:2 "python train.py --config config.yaml" Enter
# Window 3: Monitoring
tmux new-window -t $SESSION -n monitor
tmux send-keys -t $SESSION:3 "watch -n 2 'nvidia-smi && echo === Disk === && df -h'" Enter
# Attach to session
tmux attach-session -t $SESSION
Split Window for Side-by-Side Work
# Create session
tmux new-session -s work
# Split vertically (left/right)
Ctrl+B, %
# Split horizontally (top/bottom)
Ctrl+B, "
# Navigate panes
Ctrl+B, Arrow Keys
# Resize pane
Ctrl+B, (hold and drag with mouse) if mouse enabled
# Or: Ctrl+B, :resize-pane -R 10 (10 chars right)
Real-World Scenarios
Scenario 1: Long Model Download with Auto-Retry
# Create session
tmux new-session -s download -d
# Send download command with error handling
tmux send-keys -t download "
while true; do
huggingface-cli download Qwen/Qwen3.5-397B-A17B \
--repo-type model \
--local-dir ./models/qwen-397b \
--resume-download && break
echo 'Download failed, retrying in 60 seconds...'
sleep 60
done
echo 'Download complete!'
" Enter
# Check status later
tmux attach -t download
Scenario 2: Parallel Downloads
# Create session with 4 windows (one per download)
tmux new-session -s parallel_dl -d
# Model 1
tmux send-keys -t parallel_dl:0 "huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models/llama-8b" Enter
# Model 2
tmux new-window -t parallel_dl
tmux send-keys -t parallel_dl:1 "huggingface-cli download Qwen/Qwen3.5-9B --local-dir ./models/qwen-9b" Enter
# Model 3
tmux new-window -t parallel_dl
tmux send-keys -t parallel_dl:2 "huggingface-cli download mistralai/Mistral-Small-3.2 --local-dir ./models/mistral-32" Enter
# Model 4
tmux new-window -t parallel_dl
tmux send-keys -t parallel_dl:3 "huggingface-cli download google/gemma-3-4b-it --local-dir ./models/gemma-4b" Enter
# Monitor all downloads
tmux attach -t parallel_dl
Scenario 3: Training with Logging
# Create session
tmux new-session -s training -d
# Run training with timestamp logging
tmux send-keys -t training "
python train.py \\
--config config.yaml \\
--output logs/train_$(date +%Y%m%d_%H%M%S).log \\
2>&1 | tee training_$(date +%Y%m%d_%H%M%S).log
" Enter
# Check progress (attach read-only to avoid interference)
tmux attach -t training -r
Troubleshooting
Can't Find Session
# List all sessions
tmux ls
# Check if tmux server is running
ps aux | grep tmux
Session Frozen
# Kill the session
tmux kill-session -t frozen_session
# Restart
tmux new-session -s replacement
Lost Connection to SSH
# Reconnect and reattach
ssh user@host
tmux attach -t session_name
# Or create new session if lost
tmux new-session -s backup
Pane/Window Not Responding
# Kill unresponsive pane
Ctrl+B, X # Kill current pane
# Or from outside:
tmux kill-pane -t session:window.pane
Copy-Paste Not Working
# Enable mouse
set -g mouse on
# In ~/.tmux.conf, then:
tmux source-file ~/.tmux.conf
# Or use tmux selection
Ctrl+B, [ # Enter copy mode
Space # Select text
Enter # Copy
Ctrl+B, ] # Paste
Performance Tips
For Large Outputs
# Increase history limit in ~/.tmux.conf
set -g history-limit 100000
# Pipe output to file to reduce in-memory buffering
command > output.log 2>&1
For Multiple Sessions
# Keep sessions organized
tmux new-session -s project1 -d
tmux new-session -s project2 -d
tmux new-session -s downloads -d
# Manage with script:
tmux ls # See all sessions
tmux kill-session -t old_session # Clean up
SSH Timeouts
# In ~/.ssh/config
Host *
ServerAliveInterval 60
ServerAliveCountMax 3
# This prevents SSH from timing out
# tmux session will persist despite disconnection
Quick Reference Card
### Attach/Detach
tmux new -s NAME Create session
tmux ls List sessions
tmux a -t NAME Attach to session
tmux kill-session -t NAME Delete session
### Inside tmux (Ctrl+B prefix)
D Detach
(,) Previous/Next session
C Create window
N,P Next/Previous window
",% Split horizontal/vertical
Arrow Keys Navigate panes
### Useful
Ctrl+B :send-keys -t session "cmd" Enter # Send command remotely
Ctrl+B :capture-pane -p # View session output
Ctrl+B :source-file ~/.tmux.conf # Reload config
Conclusion
tmux transforms terminal workflows by enabling:
- Resilience: Tasks continue despite disconnections
- Efficiency: Monitor multiple tasks simultaneously
- Automation: Script-driven session management
- Flexibility: Works locally and over SSH
For long-running tasks like model downloads, training jobs, or system maintenance, tmux is indispensable.
Resources
- Official tmux Manual: man.openbsd.org/tmux
- GitHub Repository: github.com/tmux/tmux
- Community Configuration: github.com/tmux-plugins
- Interactive Cheatsheet: tmuxcheatsheet.com
Last Updated: March 23, 2026
Author: CLAW-00
Category: Tutorial / How-To
Difficulty: Beginner to Intermediate