TMUX – The Terminal Multiplexer (Part 1)

tmux is similar to screen as it lets you run numerous TTY’s in the same terminal window. It supports some very cool and intuitive features natively as well as a much more readable configuration syntax (ever looked at a .screenrc file?).

Why TMUX over Screen?

Well according to the FAQ for tmux it has the following advantages over screen:

  • A clearly defined cilent/server model (windows are their own clients which allows flexibility on how you handle windows. You can attach and detach different windows in different sessions without any issues)
  • Consistent, well-documented command interface. (You can use the same commands interactively as in the .tmux.conf file, more on that later)
  • Easily scriptable
  • Multiple paste buffers
  • Vi & Emacs keybindings
  • A more usable status line syntax (which also allows you to embed the output of a shell command, handy indeed.

Default keybindings & Functionality

The default keybindings for tmux are actually pretty intuitive, though if you’re used to screen you’ll likely get a little peeved with the default action binding of C-b, though this is easily changed to mimic screens behavior:

*NOTE* If you’re like me the Ctrl-b binding isn’t horribly intuitive especially if you’re used to screen. You can rebind this by putting the following in ~/.tmux.conf:

set -g prefix Ctrl-a

  • Ctrl-b c Create new window
  • Ctrl-b d Detach current client
  • Ctrl-b l Move to previously selected window
  • Ctrl-b n Move to the next window
  • Ctrl-b p Move to the previous window
  • Ctrl-b & Kill the current window
  • Ctrl-b , Rename the current window
  • Ctrl-b % Split the current window into two panes
  • Ctrl-b q Show pane numbers (used to switch between panes)
  • Ctrl-b o Switch to the next pane
  • Ctrl-b ? List all keybindings

Now these are pretty self explanatory – the real magic (for me) of tmux is the ease of modifying the default behavior to do what you want, but first things first: let’s explore the default behavior of tmux.

Basic Window Handling

Start up tmux with the tmux command and you should be greeted with a simplistic terminal window that resembles screen – the only difference is it has a default status bar which is nice (easily added to screen as well).

Terminal Multiplexer

Now let’s create a couple of windows and go through them (we’ll be using the default bindings). Hit Ctrl-b c a few times to create a few windows, you should notice that there are more tabs in the status bar.

Now if you’re like me you like to have descriptive names of which each window is for, so let’s rename them by hitting Ctrl-b ,. It should prompt you to rename the current window – type anything you want and hit enter. Now the current window is renamed to what you specified. Now going forward I’m going to have two windows open respectively named “window1” and “window2”.

Once you rename your windows lets switch back and forth. We have several different ways of switching windows, so I’ll go over the ones I personally use:

  • Ctrl-b n (Move to the next window)
  • Ctrl-b p (Move to the previous window)
  • Ctrl-b l (Move to the previously selected window)
  • Ctrl-b w (List all windows / window numbers)
  • Ctrl-b <window number> (Move to the specified window number, the default bindings are from 0 – 9)

Now these ones fairly self explanatory however they don’t really cater to a lot of different windows. What if you have 10+ windows open? It becomes quite tedious to find the window you want – but don’t fret! Tmux has a find-window option & keybinding. Type Ctrl-b f and type in the window name you want (it actually searches for the window so you can type in only part of the name of the window you’re looking for).

You can also get a list of the windows in the current session by executing the list-windows command. To execute commands interactively you type Ctrl-b : which will bring up a text prompt. From there you can execute any command tmux supports interactively (tab completion is supported).

Terminal Multiplexer - Interactive PromptTerminal Multiplexer - List Windows

Basic Pane Handling

One of the most powerful features tmux offers is the ability to split up your current window into “panes”. Anyone whose familiar with tiling windows managers will feel quite at home. It’s a bit difficult to explain this in words so a simple screenshot will suffice:

Terminal Multiplexer - Split Windows

Now here are some basic key bindings and commands to split the terminal window (vertically and horizontally) and to switch between them

  • Ctrl-b % (Split the window vertically)
  • Ctrl-b : “split-window” (Split window horizontally)
  • Ctrl-b o (Goto next pane)
  • Ctrl-b q (Show pane numbers, when the numbers show up type the key to goto that pane)
  • Ctrl-b { (Move the current pane left)
  • Ctrl-b } (Move the current pane right)

Now some obviously the default bindings don’t encompass some of features, such as splitting horizontally. I personally rebind the keys so “|” splits the current window vertically, and “-” splits it horizontally. Not the easiest things to type, though easy to remember.

You can achieve this by putting the following in ~/.tmux.conf or by typing it in the interactive prompt (Ctrl-b :). Keep in mind if you do the latter it will only be in effect for that session:

unbind %
bind | split-window -h
bind – split-window -v

Advanced Window Handling

Now that we went over the basics lets dive a little deeper into some “advanced” features of tmux. This includes moving windows around, linking windows together, switching windows from different sessions and much more. By default tmux doesn’t have key bindings for these features, so we’ll be entering them in the interactive dialog (accessed by typing Ctrl-b :) – keep in mind tmux is very scriptable and you can easily create your own key bindings for all of these.

Moving Windows

Now if you want to move a window you can use the move-window command. The command to do this:

move-window [ −d] [ −s src-window] [ −t dst-window]
swap-window [ -d] [ -s src-window] [ -t dst-window]

Similar to the above command except both windows have to exist – if they both do the window with the ID source and destination windows will be swapped.

Advanced Pane Handling

When you split up a window into multiple smaller windows they’re referred to as panes. Tmux also offers “layouts” for the panes, or the default positioning and behavior when you create a new window. You can switch through the panes by using the key binding Ctrl-b <space> which will toggle through the different layouts. Each one has different behaviors such as main-vertical which means the current active pane will take up more space in the current window, or even-vertical which will split the panes equally. Since this is difficult to describe in text I believe a few screen shots are in order:

Now that you’ve seen the different layouts let’s see what we can do with these panes. As mentioned above in the “Pane Handling” section you can switch through panes by issuing the Ctrl-b o key combination (which is using the down-pane command) or by typing Ctrl-b q which will list the pane ID’s and you select the one you want.

Make your pane into its own window

If you want to take a pane and make it into its own window you do the following:

Ctrl-b : “break-pane”

Simple enough, you should now have the pane in its brand new window. If you don’t want it to automatically make the pane you just broke out as the active window issue the “-d” switch which will simply break the pane to a new window but keep you in the current window.

Resizing Panes

You can also resize panes if you don’t like the layout defaults. I personally rarely need to do this, though it’s handy to know how. Here is the basic syntax to resize panes:

Ctrl-b : resize-pane (By default it resizes the current pane down)
Ctrl-b : resize-pane -U (Resizes the current pane upward)
Ctrl-b : resize-pane -L (Resizes the current pane left)
Ctrl-b : resize-pane -R (Resizes the current pane right)
Ctrl-b : resize-pane 20 (Resizes the current pane down by 20 cells)
Ctrl-b : resize-pane -U 20 (Resizes the current pane upward by 20 cells)
Ctrl-b : resize-pane -L 20 (Resizes the current pane left by 20 cells)
Ctrl-b : resize-pane -R 20 (Resizes the current pane right by 20 cells)
Ctrl-b : resize-pane -t 2 20 (Resizes the pane with the id of 2 down by 20 cells)
Ctrl-b : resize-pane -t -L 20 (Resizes the pane with the id of 2 left by 20 cells)
… etc

Hopefully you get the jist – don’t get confused! Simply load up a tmux session and split the window a couple of times and issue the above commands. It should become fairly evident how it behaves after fiddling with it for a bit.

Utilizing the client / server model

I’ve avoided mentioning that a lot of these commands can actually be applied to numerous tmux sessions which allows quite a bit of flexibility – the reason for avoiding it is it’s too much information all at once! An example of using this functionality is if you have two sessions open you can “link” or “move” windows across different sessions – unfortunately the actual “how-to” will be in Part 2.

Conclusion

Tmux may be a bit confusing however it’s worth putting in a few minutes to check it out and see what it has to offer – quick easy and intuitive.

Upcoming in Part 2

I’ll be going over several tips and tricks for tmux including:

  • Custom hotkeys
  • Custom window styles & colors
  • Scripting with tmux (bash, sh)
  • How to use the server / client model further
This entry was posted in General, Tips and tagged , , , , . Bookmark the permalink.

87 Responses to TMUX – The Terminal Multiplexer (Part 1)

  1. mahmoudimus says:

    I’m a big fan of tmux, I think it’s an absolutely essential part of any environment where access to a terminal is required.

    I put it in Guake (on Gnome) and just hit the hotkey, and down comes nirvana 😉

    Great blog post though, I learned a few tricks here. I think the only thing with tmux is its documentation, I’d rather have a website for documentation than reading the man page — just personal preference.

  2. Vic says:

    Front page of /r/linux, nice!

  3. andrew says:

    I feel like an idiot asking this, but I’ll blame it on my mac keyboard.

    WTF is C-b?
    Do you mean ctrl + b?
    Mac must have different scan/alt codes than a pc keyboard.

  4. Cody says:

    @Andrew Yes it’s ctrl – I use a Mac as well.

    @Vic Oh hai.

  5. Pingback: TMUX – The Terminal Multiplexer (Part 2) | Hawk Host Blog

  6. Todd H. says:

    Thanks for posting this. I have just begun using (and loving) tmux. You made some sense out of some of the commands that I didn’t understand in the man page.

  7. Thanks to your article I’ve switched from screen and added tmux support to my home skeleton script suite: http://github.com/dpc/homeskel .

  8. chytraeus says:

    tmux is part of the OpenBSD base system. Another nice write-up about it is in their FAQ:
    http://www.openbsd.org/faq/faq7.html#tmux

  9. James Pickard says:

    Great tutorial. Thanks!

  10. Todd says:

    I read the tutorial.

    I thought Yakuake is a much better tool.

    You don’t have to remember all of the commands, right click on the shell section on the right you are able to split the screens along with other things, click on the right drop down and you can enlarge the screen based on your preference. press f12 to remove the screen all together, there is a drop down that allows the user to do it automatically.

    As long as it gets the job done, I think that is all that matters.

    Todd

  11. Vlad says:

    My windows keep getting automatically renamed after I have manually renamed them. I have “setw -g automatic-rename off” in my .tmux.conf. Am I the only one with this problem?

  12. Doug says:

    I really love it. I have been screen user most of my life. I can’t seem make the vertical pane patch to work with screen 4. But now I have tmux, what the heck!!!

    One thing I find annoying is the shortcut, C-b. Man, why dont they just make it C-a. C-a is a lot more economical to type. At least for me I have to use both hands to press C-b. Is there a way to fix it?

  13. Yakuake is cool, but tmux works almost anywhere.

    @Doug: the article calls that out. Add this to your ~/.tmux.conf file:

    set -g prefix Ctrl-a

  14. Mikkel Høgh says:

    Rebinding the meta-key to Ctrl-a is accomplished like this:


    set -g prefix C-a
    unbind C-b
    bind C-a send-prefix

    The note above uses Ctrl-a which errors on my system, and neglects to unbind C-b – this snippet is from the tmux FAQ.

  15. @Vlad: Same problem here, on Mac OSX 10.6.5, iTerm and tmux 1.3 built from Macports. setw -g automatic-rename off does not seem to have any effect. Is this a general tmux 1.3 problem or is it a problem with my configuration?

  16. I seem to have another problem with tmux: In vim 7.3/Mac OSX 10.6.5, I can copy and paste to/from the system clipboard (with "+y respective "+p.) If vim is running in a tmux session, this does not work any more. Is there a way how I can get this working?

  17. Jonhnny says:

    Has it some difference to terminator (https://launchpad.net/terminator)?

  18. Gazza says:

    I’m having problems with tmux on my Mac. Tmux doesn’t seem to be reading my ~/.tmux.conf. I have tried creating another tmux.conf in /opt/local/etc/tmux.conf and even used the ‘-f’ option to specify the config file to read from but both didn’t work.

    Anyone has any advice? I’m using macports to install tmux on my system if that helps.

  19. Jeremy says:

    Same problem here, Gazza. Running Ubuntu 10.10 and using the tmux ubuntu package. Running strace on tmux shows that it runs access() on ~/.tmux.conf, but never read()’s it. Frustrating. The file is readable.

  20. Jeremy says:

    After building tmux from source, it reads ~/.tmux.conf correctly. *shrug*

  21. Farhan Ahmad says:

    If you are having issues with tmux not reading ~/.tmux.conf make sure that you have stopped all running tmux session because tmux only reads the configuration file when the server is first started.

  22. Farhan Ahmad says:

    Oh, I just found out that you can use

    Ctrl-b : source-file ~/.tmux.conf

    to rerun the config file without restarting the tmux server.

  23. Leonard says:

    The first piece of information in the post is wrong …. gack

    set -g prefix Ctrl-a
    doesn’t work on the command line or inside a tmux.conf file
    It needs to be set -g prefix C-a

    Took me 15 minutes to figure this out. Sigh.

    Othewise pretty good.

  24. dale says:

    I have the same renaming problem. Turning off automatic-rename stops the renaming based on the command I’m running in the shell, but if I login to a switch the window automatically renames whenever I enter or exit config mode. Turning set-titles off also has no effect.

  25. Red says:

    Does anyone know how to make the current working directory stay persistent after a split? Whenever I split the new shell is at home (~). I tried to map a split key like this “split-window cd $PWD” but that has its own issues with short lived commands.

  26. David Townsend says:

    I had the same problem with the automatic window renaming not working, even when “setw -g automatic-rename off” was in the conf file. The issue was it was conflicting with oh-my-zsh. If you delete the /oh-my-zsh/lib/termsupport.zsh file. It fixed my renaming issue.

  27. Gabe says:

    Tmux looks pretty cool and pretty powerful. I am a big fan of byobu ( https://launchpad.net/byobu ) which seems like it shares a lot of overall functionality with tmux.

  28. ScreenMux says:

    I love tmux, too

    but, YES but!, according to powertop, it’s way more heavier than screen (screen isn’t even on that list while tmux is usually in Top 3), I’m on a laptop so this is a issue for me

    any idea how make tmux wake up my system less often?

  29. pulsation says:

    Ctrl-b : “split-window” (Split window horizontally)
    I think Ctrl-b ” works as well?

  30. Michael Anderson says:

    I’m used to pressing “Ctrl-a” to go to the beginning of a line.
    With screen, pressing “Ctrl-a” followed by “a” sends readline a “Ctrl-a” to move the cursor to the beginning of the line.
    Any way of doing this with tmux?

  31. gazmanic says:

    c-b work too for moving around the panes.

  32. gazmanic says:

    doh! angle bracket arrow keys angle bracket got cut out by the html editor!
    c-b arrow keys work too for moving around the panes.

  33. Michael says:

    This is really cool, but does it work with the mouse?

    I have been looking for something like this except I need to be able to click anywhere in the window and have the focus and cursor jump to that point. Keyboard only won’t cut it. Apparently screen can’t do it. Emacs can do it if xterm-mouse-mode is set, but there is endless frustration for me trying to do anything complex. (For instance, if I open a terminal then ssh to another host, the ‘ls’ command displays raw escape codes instead of displaying color correctly….)

  34. winnie the pooh says:

    Ctrl-b : resize-pane (By default it resizes the current pane down)
    Ctrl-b : resize-pane 20 (Resizes the current pane down by 20 cells)

    You need to add -D for down. 🙂

  35. stuckpig says:

    I don’t remap the default C-b because I sometimes find myself running screen on a box to that doesn’t have tmux and attaching a tmux session from inside the screen session.

  36. wik says:

    I also had the problem with oh-my-zsh causing “setw -g automatic-rename off” not working in tmux, but this days it’s easy to fix, just add the following line into your ~/.zshrc:

    export DISABLE_AUTO_TITLE=”true”

    and restart the terminal.

  37. Greg H says:

    In screen, I can do Ctrl-a ” and get a list of screens, and then use the vim keys to scroll up and down (j & k). Is there a way to enable this in tmux when I have a list of windows?

  38. Mohammad says:

    I was looking for a way to resize panes, I looked here first then I remembered how I used to do it. You simply press “ctrl + b + arrow key” (all together) and it will expand/shrink depending on the arrow key that you are using. Thought this would be handy for some users

    Thanks for the tutorial btw, pretty useful! (:

  39. Falk Köppe says:

    Summary:

    Ctrl-b c Create new window
    Ctrl-b d Detach current client
    Ctrl-b l Move to previously selected window
    Ctrl-b n Move to the next window
    Ctrl-b p Move to the previous window
    Ctrl-b & Kill the current window
    Ctrl-b , Rename the current window
    Ctrl-b % Split the current window into two panes
    Ctrl-b q Show pane numbers (used to switch between panes)
    Ctrl-b o Switch to the next pane
    Ctrl-b ? List all keybindings

    Ctrl-b n (Move to the next window)
    Ctrl-b p (Move to the previous window)
    Ctrl-b l (Move to the previously selected window)
    Ctrl-b w (List all windows / window numbers)
    Ctrl-b (Move to the specified window number, the default bindings are from 0 – 9)

    Ctrl-b % (Split the window vertically)
    Ctrl-b : “split-window” (Split window horizontally)
    Ctrl-b : “break-pane” (Make pane its own window)
    Ctrl-b o (Goto next pane)
    Ctrl-b q (Show pane numbers, when the numbers show up type the key to goto that pane)
    Ctrl-b { (Move the current pane left)
    Ctrl-b } (Move the current pane right)

    Ctrl-b : resize-pane (By default it resizes the current pane down)
    Ctrl-b : resize-pane -U (Resizes the current pane upward)
    Ctrl-b : resize-pane -L (Resizes the current pane left)
    Ctrl-b : resize-pane -R (Resizes the current pane right)
    Ctrl-b : resize-pane 20 (Resizes the current pane down by 20 cells)
    Ctrl-b : resize-pane -U 20 (Resizes the current pane upward by 20 cells)
    Ctrl-b : resize-pane -L 20 (Resizes the current pane left by 20 cells)
    Ctrl-b : resize-pane -R 20 (Resizes the current pane right by 20 cells)
    Ctrl-b : resize-pane -t 2 20 (Resizes the pane with the id of 2 down by 20 cells)
    Ctrl-b : resize-pane -t -L 20 (Resizes the pane with the id of 2 left by 20 cells)

  40. I think the CMS did something to your ‘-‘ (minus), they become ‘–’ (a unicode character). So when I try to copy your line here “bind – split-window -v” tmux complains:

    unknown key: –

  41. I’m ditching OS X Terminal.app for tmux to make my working habits more portable across different flavors of *nix. This way I can more easily switch back to Ubuntu as soon as Photoshop works properly on Linux (-:

  42. Bruce says:

    Using tmux I lose the ability to access the OSX clipboard. GUI apps (gvim etc) run form inside tmux report:
    PasteBoard: Error creating pasteboard: com.apple.pasteboard.clipboard [-4960]
    PasteBoard: Error creating pasteboard: com.apple.pasteboard.find [-4960]
    and consequently have no clipboard access.
    This is the one big drawback with tmux.

    Is there some env setting or whatever I can set before starting tmux to propagate the access permissions to shells started inside tmux?

  43. tmux is well designed, documented, and useful.
    it is a great replacement for screen.
    nice outline, examples, and screenshots.
    thanks for writing. great work.

    P.S. the OpenBSD man page has some additional good examples.

    ArcticLab.org

  44. Bruce says:

    Regarding the PasteBoard: Error creating pasteboard: com.apple.pasteboard.clipboard [-4960], here’s the fix:
    https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard

  45. Jianwen says:

    I’m new to tmux. This post serves as a really nice tutorial for me.

    For “Ctrl-b : “split-window” (Split window horizontally)”, I think the key binding Ctrl-b ” works.

  46. Danil says:

    @Vlad, the same problem with autorenaming!

  47. Pingback: App Pick of the Week: tmux at romangeber.com

  48. For anyone that is running into issues with the windows auto renaming, who’s also running Zsh/Oh my zsh, I found a fix.

    Open ~/.oh-my-zsh/lib/termsupport.zsh

    Look for this line:

    if [[ "$TERM" == screen* ]]; then
    # A line of code to rename the window
    elif [[ "$TERM" == xterm* ]] ||.....

    Remove the first condition so that it just reads

    if [[ "$TERM" == xterm*]] || .....

    Remove the check for screen* altogether and this should fix it!

  49. gernb says:

    Where’s part 0 that says how to actually run tmux? It’s great to know that once it’s running there’s lots of cool keyboard commands but typing

    tmux some.host

    returns

    unknown command: some.host

  50. Just FYI,

    The recommended way of using Ctrl-a will cause tmux to throw an error, “bad key: Ctrl-a”. The proper way to do this is as follows:


    unbind C-b
    set -g prefix C-a

    You should also consider letting people edit their posts so that they don’t need to make a completely new one in order to correct a typo. Hopefully you haven’t approved that one in the moderation queue already. 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *