tmux Tutorial - Split Terminal Windows Easily

April 30, 2012 / category: Unix / 28 comments

Terminal and Terminator

It was long time ago when I realized that the major part of my work is being done in the Linux terminal. This is why I pay attention to things like shell and GNU tools, because knowing them well is often more than a half of job done.

Afterwards, I found out that having just one terminal window is not enough. Even though having many windows (represented by tabs in Linux terminal-handling tools or by many Putty instances) can solve this problem, it is often desired to keep things in sight at the same time. For example, we may want to execute some code or tests and at the same time watch over log files by using tail.

I'm about to begin writing an eBook on tmux, but I need some information first.
Please, help me by filling in a simple form. Thanks in advance!
To the survey »


Terminator seemed to me the right tool to do the job. It's easy to install and it does exactly what it's supposed to do - it can split terminal windows both horizontally and vertically, according to user's requirements. It also allows to keep multiple tabs opened in case splitting one window is not enough. Its important disadvantage is that Terminator is a GUI tool, so it won't work if an X server is not at hand.

Terminator in action:

Terminator

Of course, there is also the screen tool, but it has always been somehow mysterious to me. I was using it to run tasks in the background and to avoid problems caused by losing connection with remote machine. But I've never been brave enough to give screen the charge over my terminal windows and panes. I was pleased with Terminator, but then I found tmux.

Tmux lies somewhere between Terminator and screen, combining ease of use with basing on the plain terminal only. Here are the advantages of tmux over Terminator:

  • Portability - tmux works on all systems able to handle plain, old terminal.
  • Scriptability - tmux can be scripted, so that setting up windows and panes takes nothing more than one or two keystrokes.
  • Server-client architecture - tmux can be used to share sessions between users.
  • Tweaks and options - both tmux and Terminator are easy to get with, but it's tmux that allows to go further and offers wide range of configuration hacks.

Beginning With tmux

This is what a tmux session looks like:

tmux

By reading this section, you'll get to know how to use tmux to split terminal window into panes and how to use multiple windows. This will let you do 90% of your work.

The first thing you should know is that Ctrl+b is the default prefix in tmux. It means that running any command requires typing in the prefix first. As you probably have guessed, this is to avoid conflicts with key combinations used in other programs run in the terminal.

Here is a list of a few basic tmux commands:

  • Ctrl+b " - split pane horizontally.
  • Ctrl+b % - split pane vertically.
  • Ctrl+b arrow key - switch pane.
  • Hold Ctrl+b, don't release it and hold one of the arrow keys - resize pane.
  • Ctrl+b c - (c)reate a new window.
  • Ctrl+b n - move to the (n)ext window.
  • Ctrl+b p - move to the (p)revious window.

Other thing worth knowing is that scrolling is enabled by pressing Ctrl+b PgUp/PgDown. In fact, it enables the copy mode, which can also be done by pressing Ctrl+b [. When in copy mode, you can use PgUp/PgDown and arrow keys to scroll through the terminal contents. To (q)uit the copy mode, simply press the q key.

That should do the trick. At least, most of it.

Adjusting tmux

Your tmux configuration file should be named .tmux.conf and stored in your home directory. This is a regular text file and it's the key to adjusting tmux.

Just remember that after every modification, tmux must be refreshed to take new settings into account. This can be achieved either by restarting it or by typing in:

tmux source-file .tmux.conf

Let's start modifying .tmux.conf with a simple example.

Changing the Prefix

As we said before, tmux uses the prefix to distinguish between commands sent to tmux itself and programs running inside of it. As the default prefix (Ctrl+b) is pretty awkward, we'll replace it with Ctrl+a, which is both easier to use (a is located closer to Ctrl than b) and time-honored, as the screen tool has been using it since a long time. To change the prefix, we need to open the .tmux.conf file and type in:

unbind C-b
set -g prefix C-a

These directives are pretty self-explanatory, I hope. First we release the default prefix and then we settle a new one. Nothing to add here.

Pane switching with Alt+arrow

For pane switching, Alt+arrow key combination (which is default in Terminator) worked fine for me and didn't cause any conflicts so far, so I think it will work fine in tmux, too. But it is of course a matter of taste and you can use whatever key you want. To switch panes with Alt, you can use these directives:

bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

Make sure that you don't run tmux in the Terminator, as the latter will catch Alt+arrow combination and pane switching inside tmux won't work.

Activity Monitoring

If you have many tmux windows opened, you might want to get notified when something happens inside other windows. Pasting this:

setw -g monitor-activity on
set -g visual-activity on

into the .tmux.conf file will cause tmux to write a message and highlight the window inside of which the activity took place (that is, something was written to the output).

Highlighting Current Window Using Specified Colour

Pasting the following:

set-window-option -g window-status-current-bg yellow

into the configuration file enables highlighting the current window using the yellow colour. You may also specify one of: "black", "red", "green", "blue", "magenta", "cyan" and "white" or write "colour\d+", e.g. "colour5" or "colour170", which picks a color from the terminal's palette.

Pane Switching Using Mouse

In order to make migration from Terminator a little bit easier, you can modify tmux configuration file to allow pane switching using your mouse:

set-option -g mouse-select-pane on

Of course, this may be considered as an undesirable behaviour, as the tmux allows to boost productivity by not requiring to touch the mouse at all.

.bashrc Problem

I don't know how about you, but I like to keep a few tweaks in my rc file (.bashrc in case of bash shell). However, with tmux the .bashrc file isn't read at all. After examining things a bit, I found out that tmux tries to read .bash_profile instead of .bashrc. I won't mention rules standing behind it here as they are quite complicated, I will show you a simple workaround instead. Adding this line:

source ~/.bashrc

to .bash_profile solves the issue.

Advanced Capabilities of tmux

Scripting tmux

My favourite pane layout often looks the same every time I use tmux, of course it depends on the type of work being done. For example, working on a project may require a pane with source code, second for running tests and third one for tailing logs. Setting these panes up is a perfect example of a dull task. Then it's not a surprise that in tmux it can be automated:

selectp -t 0 # select the first (0) pane
splitw -h -p 50 # split it into two halves

selectp -t 1 # select the new, second (1) pane
splitw -v -p 50 # split it into two halves
selectp -t 0 # go back to the first pane

These commands should be saved in a separate file, e.g. .tmux/dev. In order to be able to run it, you should point to it from the .tmux.conf file:

bind D source-file ~/.tmux/dev

From now on, pressing the prefix (Ctrl+b) followed by D (it's an uppercase character in this example, so Shift is required) will execute commands located in the .tmux/dev file.

It's also worth knowing that such file can do a little more than just opening the panes. It can also run commands inside them, for example:

splitw -h -p 50 'vim' # split current pane and run 'vim' command inside the new one

Building your own scripting files won't take too much time and will pay off soon.

Sharing Session

All we've talked about so far is limited to a one-user session. As screen allows to share session, tmux is no worse. And setting things up is not too complicated.

In order to share session on the same machine, you have to explicitly give tmux the path to the Unix socket which will be used through the session lifetime:

tmux -S /tmp/our_socket

Then you have to give other users access to the newly created file:

chmod 777 /tmp/our_socket

As expected, when a new user wants to join the session, he has to pass the socket path, so that tmux knows which session is about to be used:

tmux -S /tmp/our_socket attach

Note that setting privileges to 777 is one of the dumbest things you can do, unless you fully trust your co-workers. You can also consider more sophisticated access control, SSH forwarding or give wemux a try. wemux is a set of scripts that makes sharing session easier and cleaner.

This way or another, sharing session with tmux is quite easy, though not always fully secure. It takes some time to do it right.

Summary

tmux is not a breakthrough, in fact I suppose it was never meant to be one. However, it's a breath of fresh air that made using multiple terminals a little bit easier to me. Since I feel I'm more productive with tmux, I think I'll stick to it.

Comments

There are 28 comments / Submit your comment

Felix
May 02, 2012 03:55 PM

I strongly advise you to take a look at the awesome windowmanager (http://awesome.naquadah.org/). Of course, it is yet another tool for a yet different task, but it goes along the features and philosphy you seem to like.

Lukasz Wrobel
May 02, 2012 07:00 PM

Thanks Felix, awesome window manager seems to represent a higher level concept. It doesn't try to organize space inside windows of one type only, but it organizes windows of all types instead.

Some programs (incl. e-mail clients, at least for me) are hardly replaceable with console tools, which makes awesome window manager even more hopeful. I wonder if combining awesome with software like tmux would prove its worth.

Ben
May 06, 2012 02:54 PM

I second felix on Awesome WM. It works great for maximizing screen space and keeping multiple windows open and quickly accessible. There was recently a member of the mailing list that recommended tmux for a terminal with Awesome and it sounded like a great combo.

Shfx
May 13, 2012 09:21 AM

Take a look at tmuxinator. It's quite nice when you want to work with projects that use different split panels.

Also, working with shared session with wemux :)

globetrotterdk
September 27, 2012 05:03 PM

Hi Lukasz, great posting. I used your scripting example on my laptop and it worked just fine. However, when I initiate the scriptt on my desktop machine, I get the following error:

(0) /dev/pts/2: 6 [190x30 xterm] (utf8)

Any idea what that is about?

I am using Lubuntu 12.04 on my laptop, and Ubuntu 12.04 on my home built desktop computer. In both instances, I am using Guake as my default terminal app.

Lukasz Wrobel
September 27, 2012 07:13 PM

@globetrotterdk: I'm currently using Ubuntu 11.10 and tmux scripts run without any hassle. I even tried to run them from within Guake and didn't notice any difference.

To hunt the bug, I would try to eliminate all the noise. Begin with switching to text terminal by pressing Ctrl+Alt+F1, then enable tmux. If the script fails, try to eliminate its content line by line to find which line causes the trouble.

However, if the script works under the text terminal, switch back to the graphical environment. If the script works under the default terminal-handling program, try using Guake etc.

I don't know any possible cause of an error message like the one you've provided me with, you must at least try to narrow the search.

Walter Yu
October 16, 2012 04:22 PM

Great write-up! The .term.conf file example was helpful, I now have it running in my home directory with multiple panes. w00t!

northcamel
November 01, 2012 01:53 PM

Thank you for sharing tmux~

ray
November 22, 2012 04:29 PM

Thanks for the tutorial. I'm looking for some way of having multiple terminals that can share the same environment variables in real time. Can tmux do that? Till now, I just start multiple xterms but if I set a variable in one, it's invisible in the others. Perhaps tmux can solve that?

Thanks.

Raj
November 27, 2012 04:43 AM

Great post, I was using screen all these years and discovered tmux today when searching for vertical split support. This article just got me started easily. Thanks!

Lukasz Wrobel
November 28, 2012 08:33 PM

@ray: Honestly, I don't see any simple way of achieving this. What's more, answers to this question:

http://unix.stackexchange.com/questions/8342/export-an-env-variable-to-be-available-at-all-sub-shells-and-possible-to-be-mod

dont' cheer me.

ranska
February 04, 2013 07:34 AM

Pretty usefull i will take a look at: wemux. thank's

Yann
July 02, 2013 11:16 AM

Thanks for your post. This is the first one that made me change my mind. Clearly tmux used that way fit my needs.

Parakram Majumdar
August 12, 2013 09:10 AM

Very nice article; I would say it's better than most others in terms of readability. But can you also include a more exhaustive cheat sheet? "How to rename window" is what i was looking for, but couldn't locate.

Lukasz Wrobel
August 12, 2013 08:12 PM

@Parakram: I'd like to keep this article simple, though providing a separate, more detailed cheat sheet sounds like a good idea.

To rename a window in tmux, type in Ctrl+b and press the "," key (comma). Then hold backspace to erase the old name, provide a name of your own and confirm it by pressing Enter.

Rohit Nair
November 28, 2013 07:41 PM

Thank you, this article saved a lot of time for me.

Jimmy
January 03, 2014 01:30 PM

@globetrotterdk: I get almost precisely the same error, "(0) /dev/pts/0: 7 [80x24 xterm] (utf8)" I'm in Ubuntu 12.10, and the error occurs even with an empty script file. Did you solve your problem?

Jerzy Nowakowski
January 18, 2014 03:52 PM

C-a is jump-to beginning of the line command Binding this way the command is blocked I used C-x instead.

Thanks for a great tutorial

Joseph Rex
February 02, 2014 09:37 PM

I feel really reluctant reading man pages. Your article made it all really clear to me and I started using Tmux from this moment. Thanks for the great article!

Gary Ferguson
February 27, 2014 09:55 PM

As mentioned earlier Tmuxinator is a great way to set up tmuxinator for different projects.

The two combined make a great tool.

Johan Krafft
March 09, 2014 04:51 PM

Thanks for a great tutorial. I'm diving into Linux, and tmux has made my experience in the OS a lot smoother :) Thank you!

asdfasdf
March 19, 2014 07:23 AM

thanks! for using `screen' as a reference. It helps me migrate to tmux

Stasiek
March 27, 2014 10:07 PM

i3 >> AwesomeWM

rtmie
March 29, 2014 12:00 PM

Really nice step by step intro. Thanks.

Rick
June 03, 2014 05:23 PM

I tried the first 3 lines in .tmux/dev

selectp -t 0 # select the first (0) pane
splitw -h -p 50 #  split it into two halves
selectp -t 1 # select the new, second (1) pane

It splits the terminal into 2 vertical panes. Isn't -h suppose to split it into horizontal panes?

Lukasz Wrobel
June 03, 2014 06:53 PM

@Rick: The commands you provided work as they're supposed to. The problem is in the tmux naming convention, which we both (and not only we) seem to find counterintuitive.

Take a look at these examples:

Nikos
September 19, 2014 02:12 PM

Great article.. Thanks for showing this amazing tool to us!

Ganapathi K
October 17, 2014 02:36 PM

I landed on your write up on tmux after going through lot of sites. Your document is simple and practical. It is really great.

-Ganapathi, Chennai,India

You can use Markdown in your comments if you wish. Examples:

*emphasis*
emphasis
**strong**
strong
`inline code`
inline code
[My blog](http://lukaszwrobel.pl)
My blog
# use 4 spaces to indent
# a block of code
    def my_method(x)
      x = x + 1
    end
def my_method(x)
  x = x + 1
end

* First.
* Second.
  • First.
  • Second.

> This is a citation.
> Even more citation.

I don't agree with you.

This is a citation. Even more citation.

I don't agree with you.


Submit your comment

(required)

(optional)

(required, Markdown supported)


Preview:

My eBook: “Memoirs of a Software Team Leader”

Read more »