tmux quickstart

By Michael Anckaert - last updated on and originally published on - posted in Commandline

tmux is a so called terminal multiplexer. tmux allows you to run multiple terminals (and thus terminal programs) and perform some very advanced window management.

The architecture behind tmux is a tmux client that connects to a tmux server. You interact with the tmux client while the server runs your programs. This architecture enables you to start long running programs on a server and then disconnect. You can attach to the same tmux session later to resume your interaction with the program.

If you're impatient, here's a small cheatsheet you can refer to:

Command Description
$ tmux Start tmux and create a new session
$ tmux attach Start tmux and try to connect to an existing session
Key Combination Description
CTRL+B c Create a new window
CTRL+B n Move to next window
CTRL+B p Move to previous window
CTRL+B <index> Move to window with index <index>
CTRL+B d Detach from session
CTRL+B , Rename window
CTRL+B " Split window horizontally (creates a new pane)
CTRL+B % Split window vertically (creates a new pane)
CTRL+B o Move to other page

Starting tmux

To start tmux just enter tmux at the commandline:

$ tmux

This will start tmux in client mode and try to attach it to a running server. If there is no server running, it will automatically start one for you.

If everything went well you will find yourself looking a new blank, empty command prompt. But at the bottom of the screen you will see the tmux statusbar.

tmux statusbar view image

When tmux started it created a new window for you and started your login shell (in this example it's Bash). The window index is 0 (zero), and the window is called bash. You interract with your shell just like with a normal shell.

Creating a new window

Let's create a new window in our tmux session. Press CTRL+B and then c to create an new window.

New window created view image

The statusbar will show your new window with the window index 1. You'll also notice the asterisk next to the window name, this indicates the active window. When tmux created your new window it automatically switched to it, so the window with index 1 is now active.

Again, this is just another normal Bash shell, but embedded within tmux.

But having all those windows named bash can get quite confusing fast. Don't worry, we'll just rename the window. Press CTRL+B and then , (comma) to rename the current window.

Now let's switch back to our first terminal. There are a number of ways to do so. Pressing CTRL+B and then 0 will activate the window with index 0. To move back to index 1, press CTRL+B and then 1.

Another easy combination is CTRL+B and then n to move to the next window, and CTRL+B and then p to move to the previous window. tmux will wrap to the start or end of the window list if required.

Killing windows

If you want to close a window, you can either exit the terminal running in that window or you can kill the window.

To kill the window use the key combination CTRL+B and then &.

Detaching from a session

We've stayed in our tmux session up until now. But let's say you wanted to disconnect from your session and then continue at a later time. Maybe you're connected to a server while at work and have to head home, but you want to continue your work tomorrow.

To detach from a session, press the key combination CTRL+B and then d. This detaches your tmux client from the server. You can then close your terminal window, shutdown your computer or whatever. The shells and other programs running in your tmux session will hapilly keep on running.

Attaching to a session

If you want to reattach to a session, start the tmux client with the option attach:

$ tmux attach

This will start the tmux client and automatically connect it a running tmux session. You should find all your shells and other programs where you left them.

Splitting windows in panes

Modern screens are huge and effective window management can improve your productivity a lot. That's why I'm such a fan of tiling window managers.

tmux has some nice window management tricks you can use. One of those tricks is splitting a window in panes. Just like a real life, physical window. tmux always shows one window at a time, but you can split it into multiple panes, each running their own application.

Splitting happens in two dimensions: horizontally and vertically.

To to split your current window horizontally by pressing CTRL+B and then %. You'll notice that tmux splits your window straight in the middle and starts a new terminal in the new pane.

Splitting a tmux window in horizontal panes view image

Now you can split that pane again, for example vertically by pressing CTRL+B and then ".

Splitting a tmux window in vertical panes view image

There is no limit to how much you can split a pane. Just remember not go too crazy ;-)

Don't go crazy splitting tmux panges view image

Advanced usage

You can enter 'tmux commands' by pressing CTRL+B :. You'll see a small commandprompt open at the bottom of your tmux window where you can enter 'tmux commands'. Here are some useful commands:

Resize panes

resize-pane -U 10 Resize the current pane upwards for 10 'units' resize-pane -D 10 Resize the current pane downwards for 10 'units' resize-pane -L 10 Resize the current pane to the left for 10 'units' resize-pane -R 10 Resize the current pane to the right for 10 'units'

Join panes

join-pane -s 1 -t 0 Join the pane with source 1 to the window in target 0. This command can also be used to move the contents of a window to another window.

Break out pane to window

To move a pane to it's own window, press CTRL+B !

More information

tmux allows you to do so much more. Be sure to check out the man page ($ man tmux) and have a look at all possible options. Another great option is