DEV Community

Cover image for The Modes of tmux
Josh Branchaud
Josh Branchaud

Posted on • Updated on

The Modes of tmux

tmux is a tool that is so ingrained in my setup and workflow, that I almost forget it is there. Because of that, I use it in very specific ways and tend not to learn other features or ways of doing things.

As I've rebuilt my tmux config from scratch, I've learned a bunch of new things. One of those things in particular stands out.

tmux is modal.

What does it mean that it is modal?

That means that tmux has different modes that it operates in. There are certain features, capabilities, and keybindings associated with each mode. Work will happen in one mode, then when you need to do something unique to one of the other modes, you switch to that other mode. When you're done, or as the result of completing an action, you'll switch back to the original mode. This is what it means for a tool to be modal (Vim is another, perhaps more notably modal tool).

tmux has four (five really, but I won't get into command mode) modes that I tend to operate in as I use it day to day. The primary mode (which doesn't have a name from what I can tell) is the mode I'm in 99% of the time. Because of that and because it is essentially a window through which I'm viewing the terminal, it tends to feel invisible.

From this primary mode, I can switch to three other modes.

  1. Copy Mode
  2. View Mode
  3. Choose Mode

Let's look at each of these in turn.

Copy Mode

Copy mode allows me to navigate to anywhere in the history of the current pane, make a selection, and copy that to the paste buffer.

Copy mode can be switched to by hitting <Prefix [. From here, depending on which key-mode is configured, I can navigate around, search, make a visual selection, and then copy that to the tmux paste buffer. Copying a selection or hitting enter will return me to the primary mode.

View Mode

View mode is similar to Copy Mode, but is the result of a keybinding that produces output, such as list key bindings (<Prefix> ?).

Another example of view mode is list-keys (activated by executing <Prefix>:list-keys) which shows all the keybindings that are set up for this context (session, window, pane). Hitting enter will return me to the primary mode.

Choose Mode

Choose mode displays a list of options and allows me to choose one of those options. choose-buffers is a great example of this, allowing me to browse and select from tmux's copy buffer history.

<Prefix> s (choose a session) and <Prefix> w (choose a window) are other examples of bindings that put me into choose mode. After making a selection from one of these, I'll be switched to the particular session or window and placed back in the primary mode.

Custom Keybindings

When adding custom keybindings to your tmux config that are meant to work in copy-mode, you'll need to specify the binding's key table as copy-mode.

bind-key -T copy-mode 0 send-keys -X start-of-line
Enter fullscreen mode Exit fullscreen mode

You can look up copy-mode (and copy-mode-vi) bindings with the list-keys command:

$ tmux list-keys -T copy-mode
Enter fullscreen mode Exit fullscreen mode


You'll spend most of your time in the primary mode, but it's invaluable to have an understanding of the other modes and how you get there. Knowing your tool will allow you to make the most of it.

If you enjoyed this post, join my newsletter to get a direct line on more stuff like this.

Cover photo by David Watkis on Unsplash

Top comments (2)

michaeldimmitt profile image

The primary mode (which doesn't have a name from what I can tell)

@jbranchaud , this mode, looks like Default Mode, even though it is not defined in the tmux man page.

Described in Getting Started with tmux - By Victor Quinn

I searched the tmux code base and it seemed no enum actually naming the modes. There are a few case statements like found in the following location:

File: tmux/screen.c - function: screen_set_cursor_style()
default mode is pane_in_mode: 0
command mode is pane_in_mode: 1

I am able to see the mode number change by using the following command:
tmux display-message -a | grep pane

I did not talk to anyone who works on tmux, but do enjoy using the program. So my information here may be incomplete. Anyway it is surprisingly hard to google and find information about these modes so thanks for writing this blog post.

If I find some stronger information / official docs, I will add a followup comment. 👍

antoinemarteau profile image

Hey thanks for this great summary about tmux's modes !

What are View mode and Choose mode default mappings and how to change them ?
I use "bépo" keyboard layout and need to remap Left Down Up Right to c t s r.
There are no view or copy mode mappings in tmux list-keys …

Changing Copy mode mapping had no effect on View and Choose modes.