> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpod.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Using TMUX for persistent sessions

TMUX is a terminal multiplexer that creates persistent terminal sessions on your Pod.

## Why use TMUX

While you can run long-running tasks in JupyterLab notebooks, the kernel can crash unexpectedly, losing hours or days of computation. TMUX runs your commands in persistent terminal sessions that continue even if JupyterLab crashes or you disconnect.

## Requirements

To use TMUX, you need terminal access to your Runpod Pod (SSH, web terminal, or JupyterLab terminal).

## Video tutorial

For a comprehensive video guide on using TMUX, check out this excellent tutorial: [TMUX Tutorial on YouTube](https://youtu.be/nTqu6w2wc68?si=w0_TiikbaFVb-aCr)

## Installing TMUX

TMUX is not installed by default on Runpod Pods. To install it, run:

```bash Install TMUX theme={"theme":{"light":"github-light","dark":"github-dark"}}
apt-get update && apt-get install -y tmux
```

<Note>
  Most Runpod templates are based on Ubuntu/Debian images that support `apt-get`. If you're using Alpine Linux, use `apk add tmux` instead. Some minimal images may lack required dependencies.
</Note>

## Practical example: running model training

Here's a typical workflow for running long-duration model training:

```bash Training workflow theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Start a new TMUX session
tmux new -s model_training

# Navigate to your project directory
cd /workspace/my_project

# Start your training script
python train.py --epochs 100 --batch-size 32

# Detach from the session with Ctrl+B, then D
# You can now safely disconnect from the Pod

# Later, reconnect to the Pod and reattach
tmux attach -t model_training
```

## Command reference

### Starting a new session

Create a new TMUX session with a descriptive name:

```bash Create named session theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux new -s training
```

### Detaching from a session

To detach from a session and leave it running in the background, press:

```
Ctrl+B, then D
```

Your processes will continue running even if you disconnect from the Pod.

### Listing active sessions

View all active TMUX sessions:

```bash List sessions theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux ls
```

### Reattaching to a session

Reconnect to a previously created session:

```bash Reattach to session theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux attach -t training
```

### Killing a session

End a session when you no longer need it:

```bash Kill session theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux kill-session -t training
```

### Killing all sessions

If you need to restart fresh and kill all TMUX sessions:

```bash Kill all sessions theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux kill-server
```

Alternatively, you can kill all sessions except the current one:

```bash Kill other sessions theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux kill-session -a
```

## Advanced TMUX features

### Window management

TMUX supports multiple windows within a session:

* `Ctrl+B, C` - Create new window
* `Ctrl+B, N` - Next window
* `Ctrl+B, P` - Previous window
* `Ctrl+B, 0-9` - Switch to window by number

### Pane splitting

Split your terminal into multiple panes:

* `Ctrl+B, %` - Split vertically
* `Ctrl+B, "` - Split horizontally
* `Ctrl+B, Arrow keys` - Navigate between panes
* `Ctrl+B, X` - Close current pane

### Scrolling and copy mode

To scroll through terminal output:

1. Enter copy mode: `Ctrl+B, [`
2. Use arrow keys or Page Up/Down to scroll
3. Press `q` to exit copy mode

## Best practices

When using TMUX on Runpod Pods, keep these tips in mind:

* Always name your sessions descriptively to easily identify them later.
* Regularly check on long-running processes by reattaching to sessions.
* Clean up finished sessions to avoid confusion.
* Use TMUX for any process that takes longer than a few minutes to complete.
* Consider creating a TMUX session immediately when connecting to a Pod for important work.

## Troubleshooting

If you can't reattach to a session after reconnecting to a Pod, the Pod may have been restarted. TMUX sessions don't persist across Pod restarts, so ensure you save your work regularly and use network volumes for persistent storage.