Note: I originally wrote and published this article as a DigitalOcean Community Tutorial.
Byobu is an easy-to-use wrapper around the
screen) terminal multiplexer. This means that it makes it easy for you to open multiple windows and run multiple commands within a single terminal connection.
Byobu’s primary features include multiple console windows, split panes within each window, notifications and status badges to display the status of the host, and persistent sessions across multiple connections. These provide you with a lot of different options and possibilities, and it is flexible enough to get out of your way and let you get things done.
This tutorial will cover how to install and configure Byobu as well as how to use its most common features.
For this tutorial, you will need:
- One Ubuntu 16.04 server with a sudo non-root user, which you can set up by following this initial server setup tutorial.
Step 1 — Installing Byobu
Ubuntu should come with Byobu installed by default, so here, we’ll check that it’s installed and then configure some if its settings.
To check that Byobu is installed, try running this command to output its version.
byobu version 5.106tmux 2.1
If that does not display the current version number, you can manually install Byobu using
sudo apt-get install byobu.
Now that Byobu is installed, we can configure some options.
Step 2 — Starting Byobu on Login
Byobu is disabled by default after installation. There are two main ways you can enable Byobu: you can manually start it with the
byobu command every time you want to use it, or you can set it to start automatically when you log in to your account.
To add Byobu to your login profile, run the following command. This means that every time you log in to your account, it will be launched.
The Byobu window manager will be launched automatically at each text login.
If you change your mind later on and want to disable Byobu on login, run
Because Byobu sessions are maintained across multiple login sessions, if you don’t specifically close a Byobu session, it will be loaded again the next time you log in. This means you can leave scripts running and files open between connections with no problems. You can also have multiple active logins connected to the same session.
Once Byobu is configured to start on login if you want it to, you can customize which multiplexer it uses.
Step 3 — Setting the Backend Multiplexer
By default, Byobu will use
tmux as the backend multiplexer. However, if you prefer to use
screen, you can easily change the enabled backend.
This will give you a prompt to choose the backend multiplexer. Enter the number for whichever you prefer, and then press
Select the byobu backend: 1. tmux 2. screen Choose 1-2 :
This tutorial assumes you have the
tmux backend enabled, however, the default keybindings should be the same with
screen as well.
Step 4 — Enabling the Colorful Prompt
Byobu also includes a colorful prompt which includes the return code of the last executed command. It is enabled by default in some environments. You can manually enable it (or check that it’s already enabled) by running:
After this, you’ll need to reload your shell configuration.
Byobu’s colorful prompt looks like this:
If you change your mind later on and want to disable Byobu’s colorful prompt, you can run
Byobu is fully configured now, so let’s go over how to use it.
Step 5 — Using Sessions
Byobu uses the function keys (
F12, the top row of your keyboard) for the default keybindings which provide access to all of the available functions. In the next few steps, we’ll talk about the keybindings for sessions, windows, and panes.
A session is simply a running instance of Byobu. A session consists of a collection of windows, which are basically shell sessions, and panes, which are windows split into multiple sections.
The first time you start Byobu, it starts you a fresh session in which you create windows and panes. On subsequent connections, if you have only one session open, Byobu will automatically open that session when you connect; if you have more than one session open, Byobu will ask you which session you want to use with a prompt like this:
Byobu sessions... 1. tmux: 1: 1 windows (created Wed Aug 3 16:34:26 2016) [80x23] 2. tmux: 2: 1 windows (created Wed Aug 3 16:34:38 2016) [80x23] 3. Create a new Byobu session (tmux) 4. Run a shell without Byobu (/bin/bash) Choose 1-4 :
One reason to use sessions is because each session can have its own window size, which is useful if you’re connecting with multiple devices with different screen sizes (say, a phone and a desktop computer). Another reason to use sessions is simply to have a clean workspace without closing your existing windows.
First, SSH into your server and enable Byobu, if it isn’t already enabled from the previous steps. Start a new session by pressing
CTRL+SHIFT+F2, then use
ALT+DOWN to move backwards and forwards through your open sessions.
You can press
CTRL+D to exit Byobu and close all of your sessions. If you instead want to detach your session, there are three useful ways to do this.
F6 cleanly detaches your current session and logs you out of the SSH connection. It does not close Byobu, so the next time you connect to the server, the current session will be restored. This is one of the most useful features of Byobu; you can leave commands running and documents open while disconnecting safely.
If you wish to detach the current session but maintain an SSH connection to the server, you can use
Shift-F6. This will detach Byobu (but not close it), and leave you in an active SSH connection to the server. You can relaunch Byobu at any time using the
Next, consider a scenario where you are logged into Byobu from multiple locations. While this is often quite a useful feature to take advantage of, it can cause problems if, for example, one of the connections has a much smaller window size (because Byobu will resize itself to match the smallest window). In this case, you can use
ALT+F6, which will detach all other connections and leave the current one active. This ensures only the current connection is active in Byobu, and will resize the window if required.
CTRL+SHIFT+F2will create a new session.
ALT+UPand ALT+DOWN` will scroll through your sessions.
F6will detach your current Byobu session.
SHIFT+F6will detach (but not close) Byobu, and will maintain your SSH connection to the server. You can get back to Byobu with the
ALT+F6will detach all connections to Byobu except for the current one.
Next, let’s explore one of Byobu’s features: windows.
Step 6 — Using Windows
Byobu provides the ability to switch between different windows within a single session. This allows you to easily multi-task within a single connection.
To demonstrate how to manipulate windows, let us consider a scenario where we want to SSH into a server and watch a system log file while editing a file in another window. In a Byobu session, use
tail to watch a system log file.
sudo tail -n100 -f /var/log/syslog
While that is running, open a new window by pressing
F2, which will provide us with a new command prompt. We’ll use this new window to edit a new text file in our home directory using
We now have two windows open: one tailing
/var/log/syslog and the other in an editor session. You can scroll left and right through your windows by using
F4 respectively. You can also give these windows names so it’s easier to organize and find them. To add a name to your current window, press
F8, then type in a useful name (like “tail syslog”), and press
ENTER. Scroll through each window and name them. If you want to reorder them, use
CTRL+SHIFT+F3/F4 to move the current left or right through the list, respectively.
At this point, there should be some log entries in syslog. In order to look through some of the older messages that are no longer being displayed on the screen, scroll to the log window and press
F7 to enter the scrollback history. You can use
PageDown to move through the scrollback history. When you are finished, press
Now, if you need to disconnect from the server for a moment, you can press
F6. This will clearly end the SSH connection and detach from Byobu. When it has closed, you can use SSH to reconnect again, and when Byobu comes back, all three of our existing windows will be there.
F2creates new windows within the current session.
F4scroll left and right through the windows list.
CTRL+SHIFT+F3/F4moves a window left and right through the windows list.
F8renames the current open window in the list.
F7lets you view scrollback history in the current window.
Using just a few options, you have performed a number of useful actions that would be hard to easily replicate with a single standard SSH connection. This is what makes Byobu so powerful. Next, let’s extend this example by learning how to use panes.
Step 7 — Using Panes
Byobu provides the ability to split windows into multiple panes with both horizontal and vertical splits. These allow you multi-task within the same window, as opposed to across multiple windows.
Create horizontal splits in the current window panel by pressing
SHIFT+F2, and vertical ones with
CTRL+F2. The focused pane will be split evenly, allowing you to split panes as much as is required to create quite complex layouts. Note that you cannot split a pane if there is not enough space for the pane to split into two.
Once you have split a window into at least two panes, navigate between them using
SHIFT+F3/F4. This allows you to leave a command running in one pane, and then move to another pane to run a different command. You can reorder panes by using
CTRL+F3/F4 move the current pane up or down, respectively.
SHIFT+ALT+LEFT/RIGHT/UP/DOWN allows you to manipulate the width and height of the currently selected pane. This will automatically resize the surrounding panels within the window as the split is moved and makes it easy to make a pane a lot larger when you are working in it, and then enlarge a different pane when your focus has shifted.
You can also zoom into a pane with
SHIFT+F11, which makes it fill the entire window; pressing
SHIFT+F11 again switches it back to its original size. Finally, if you want to split a pane into a completely new window, use
SHIFT+F2creates a horizontal pane;
CTRL+F2creates a vertical one.
SHIFT+F3/F4switches between panes.
CTRL+F3/F4moves the current pane up or down, respectively.
SHIFT+ALT+LEFT/RIGHT/UP/DOWNresizes the current pane.
SHIFT+F11toggles a pane to fill the whole window temporarily.
ALT+F11splits a pane into its own new window permanently.
In the example from Step 7, it would’ve have been easy to use splits instead of windows to allows us to have the syslog tail, editor window, and new command prompt, all open in the same window. Here’s what that would have looked like with one window split into three panes:
Now that you know how to use sessions, windows, and panes, we’ll cover another one of Byobu’s features: status notifications.
Step 8 — Using Status Notifications
Status notifications are notifications in the status bar at the bottom of a Byobu screen. These are a great way to customize your Byobu experience.
F9 to enter the Byobu configuration menu. The options available are to view the help guide, toggle status notifications, change the escape sequence, and toggle Byobu on or off at login. Navigate to the Toggle status notification option and press
ENTER. The list of all available status notifications will be displayed; you can select the ones you wish to enable or disable.
When status notifications are enabled, they will appear in the bottom status bar, alongside the window indicators. By default there are a couple enabled, usually including the date, load and memory. Some notifications have options that can be configured through config files, which we will cover in the next tutorial.
There are a lot of different notifications to choose from, some of the commonly used ones are:
archshows the system architecture, i.e.
- `battery shows the current battery level (for laptops).
dateshows the current system date.
diskshows the current disk space usage.
hostnameshows the current system hostname.
ip_addressshows the current system IP address.
load_averageshows the current system load average.
memoryshows the current memory usage.
networkshows the current network usage, sending and receiving.
reboot_requiredshows an indicator when a system reboot is required.
releaseshows the current distribution version (e.g. 14.04).
timeshows the current system time.
updates_availableshows an indicator when there are updates available.
uptimeshows the current system uptime.
whoamishows the currently logged in user.
After selecting the status notifications you wish to enable, select Apply. You may need to press
F5 to refresh the status bar; an indicator in the status bar will appear, if required.
Status notifications are a great way to see the information you care about in your system at a glance.
There’s a lot more that Byobu is capable of. You can read Byobu’s man pages for more detail, but here are a few more useful keybindings:
SHIFT+F1displays the full list of keybindings. If you forget every other keybinding, just remember this one! Press
SHIFT+F12toggles whether keybinding are enabled or disabled. This comes in handy if you are trying to use another terminal application within Byobu that has conflicting keyboard keybindings.
CTRL+F9opens a prompt that lets you send the same input to every window;
SHIFT+F9does the same for every pane.
As you can see from the wide range of functions that we have covered, there are a lot of things that Byobu can do and there is a good chance that it will fit into your workflow to make getting things done easier.