Tmux is a terminal multiplexer, enabling a number of terminals to be created, accessed, and controlled from a single screen. Tmux may be detached from a screen, continue running in the background, and then later reattached, even after logging out from CARC systems.
Some use cases for tmux on CARC systems are:
- Backgrounding long-running data transfers
- Splitting the screen of one terminal into "panes" for interactive jobs
- For developing scripts and programs interactively
- For process monitoring
- Saving terminal sessions
- Restarting dropped terminal sessions
Using tmux on CARC systems
You can use tmux by loading a corresponding software module. For example:
module load gcc/11.3.0 tmux/3.3a
A tmux process is unique to a node, so if you're using tmux on a login node, make sure to always log in to the same login node if you want to reattach to previous tmux sessions. Instead of logging in to
endeavour.usc.edu, choose a specific login node:
The tmux module sets the
TMUX_TMPDIR to a
/scratch1/<username>/tmux/<hostname> directory. All tmux session information will be saved here. You can set this variable manually, after loading the module, if you want to save the session information to a different location.
Also keep in mind that login nodes are rebooted every so often, such as during maintenance periods. If you want to keep tmux session information across reboots, then you would need to use a plugin like Tmux Resurrect.
To see the manual page, enter
Basic tmux workflow
After loading the module, tmux can be used on a login or transfer node as well as on a compute node during an interactive job.
A typical tmux workflow looks like the following:
- Start a new session
- Detach from session
- Reattach to session
- Work (return to step 3 if needed)
- End session
Start a new session
To start a new named session, enter:
tmux new -s <name>
Make sure to use a descriptive session name.
If you want to use tmux with an interactive job, first start a new tmux session on a login node, and then use
salloc from within that session to start an interactive job. This will keep the job running even if you detach from the session and log out (e.g., disconnections). For general information on jobs, see our Running Jobs user guide.
After the tmux session opens, you can then run a process, develop scripts or programs, etc.
The following table describes some useful key bindings:
|Split the terminal screen vertically|
|Split the terminal screen horizontally|
|Move to different panes|
|Scroll through pane output|
|Detach from session|
|Close pane / end session|
Detach from session
To detach from a tmux session, use the key binding
D. This will return you to the original shell where you started the tmux session.
Reattach to session
At a later time, even after logging out of CARC systems, you can reattach to a previous tmux session as long as you are on the same login or transfer node where the tmux session was created. If you only have one previous tmux session, to reattach simply enter:
If you have multiple sessions, first list the sessions:
Then use the session name or ID to reattach to that session:
tmux a -t <name>
Once you are done with a session, you can end the session by entering
exit or using the key binding
Ctrl+D from within the session (multiple times if you have multiple panes open).
Alternatively, from outside the tmux session, enter:
tmux kill-session -t <name>
The look and behavior of tmux can be customized by creating and modifying the configuration file
~/.tmux.conf. For more information, see the following guide: https://www.hamvocke.com/blog/a-guide-to-customizing-your-tmux-conf/.
There are also a number of tmux plugins available. For more information, see the tmux plugin manager: https://github.com/tmux-plugins/tpm.
If you have questions about or need help with tmux, please submit a help ticket and we will assist you.