Introduction to `tmux`

Written by Anqi Wang, December 2023

tmux is a terminal multiplexer that allows you to manage multiple terminal sessions in a single terminal window and also helps you to run code in the background and keep it running even after you log out of your terminal session.

Install tmux on your system

For the conda user,

conda install tmux

For the micromamba user,

micromamba install tmux -y

Verify tmux installation

After installation, you can verify that tmux is installed correctly by running:

tmux -V

This should display the version of tmux installed.

Start a new tmux session

For your first session simply start tmux with a fresh session:

tmux

This will create a new tmux default session (number 0), with a nice all-green status bar at the bottom: the status bar is an important part of tmux. Apart from the currently opened windows (on the left) it also shows some system information like date and time (on the right). The status bar can also be customized. Now that you’re connected to tmux, you can run any commands or programs as you normally would, particularly a long-running command.

In tmux, the first launched window is numbered as 0, the second window is numbered as 1, and so on. These windows correspond to sessions. Using numeric identifiers to distinguish sessions may not be very intuitive, a better approach is to give sessions meaningful names in the local terminal.

tmux new -s <session-name>

For example,

tmux new -s Mic

To exit a tmux window, you can either press Ctrl+d or explicitly enter the ‘exit’ command.

exit

Manage Sessions

View Sessions

To view tmux sessions from the local terminal, run one of the following commands:

tmux ls

tmux list-session

We would see the tmux session information like this:

Exc: 1 windows (created Wed Dec 20 15:36:30 2023)
Mic: 1 windows (created Wed Dec 20 10:55:07 2023)

Rename Sessions

To rename sessions, from the local terminal, we run the following command:

tmux rename-session -t <session-name> <new-session-name>

Alternatively, we may also hit Ctrl + b + $ to rename the current session in the tmux terminal.

Detach Sessions

In a tmux window, pressing Ctrl+b followed by ‘d’ or entering the tmux detach command will detach the current session from the window.

tmux detach

After executing the above command, the current tmux window will exit, but the session and its processes will continue to run in the background.

Attach Sessions

The tmux attach command is used to reattach to an existing session.

###use session name
tmux attach -t <session-name>

###use session number
tmux attach -t 0

Switch Sessions

###use session name
tmux switch -t <session-name>

###use session number
tmux switch -t 0

Kill Sessions

###use session name
tmux kill-session -t <session name>

###use session number
tmux kill-session -t 0

Example to upload data from HPC to AWS

tmux new -s upload
aws s3 cp /mnt/vast/hpc/csg/FunGen_xQTL/ROSMAP/Genotype/geno_by_region/TADB_enhanced_cis_genotype_by_region/ROSMAP_NIA_WGS.leftnorm.bcftools_qc.plink_qc.ENSG00000158869.bed s3://statfungen/ftp_fgc_xqtl/ROSMAP/genotype/analysis_ready/geno_by_region/ROSMAP_NIA_WGS.leftnorm.bcftools_qc.plink_qc.ENSG00000158869.bed

pressing Ctrl+b+d to dettach the sessions, this process will keep running in the background. Then in the HPC terminal, using the following command to attach the session to check the status

tmux attach -t upload

Introduction to tmux