Join my Bash scripting course on Udemy 👀

List tmux sessions

March 5, 2020  ‐ 3 min read

Tmux has the concepts of sessions, you can look at a session as a workspace for your terminal. This is convenient when you're working on a project, creating panes and windows, but have to switch to something different in between. In this case you can just keep this specific session running so you can come back to it later. When you're working with multiple sessions it can be useful to list the ones that are active at the moment.

To list all the sessions that are currently managed by the tmux server you can use the tmux list-sessions command. The command shows by default the name of the sessions, the amount of windows per session, when the session was created and whether the session is currently attached to a terminal.

$ tmux list-sessions
first_project: 4 windows (created Wed Mar  4 18:17:14 2020)
second_project: 2 windows (created Wed Mar  4 19:00:55 2020) (attached)

Like many tmux commands list-sessions has the shorthand too, tmux ls shows you the same information.

$ tmux ls
first_project: 4 windows (created Wed Mar  4 18:17:14 2020)
second_project: 2 windows (created Wed Mar  4 19:00:55 2020) (attached)

Both of the examples above have an equivalent in the command mode of tmux. To start the command mode use <prefix> :. Now you can enter :list-sessions or :ls to see a list of active tmux sessions.

You can use these to make a custom keybinding in your .tmux.conf file. An example would be:

bind <key> list-sessions

By default, list-sessions is binded to the key combination <prefix> s. You can navigate the session list with j and k and activate one by pressing enter. If your main purpose is to switch session you can try out choose-session, it is more verbose and gives you the possibility to switch to a specific window too.

Format the output

You can specify the format of the session list with the -F option. When you're scripting with tmux this can be a useful feature. For example, if your script requires the session names you can use the following command.

$ tmux ls -F "#{session_name}"
first_project
second_project

You can ofcourse use multiple variables in the format string. The output below shows the name of the active window in each session.

$ tmux ls -F "#{session_name}:#{window_name}"
first_project:database
second_project:server

The FORMAT section in the man pages lists a whole lot more options for formatting the output of list-sessions.

Learn more

A great resource for learning more about tmux are its man pages. You can read them online here or from the command-line using the following command:

$ man tmux

Or take a look at this book: