Switch Default Backends with byobu-select-backend

byobu-select-backend switches whether a bare byobu launch grabs tmux or GNU Screen. You will set the default, check that the value was saved, and switch back without touching a session that is already running. Allow about ten minutes; you need the byobu package and an ordinary shell, no sudo.

This guide describes the installed Byobu 6.11 package, version 6.11-0ubuntu1.1. The command only changes the default used when you run byobu with no backend helper: it does not convert, stop or reconfigure a session already running under the other backend.

1. Check the available command

Confirm that the selector is installed and see which backend programs are available. This is read-only:

$ command -v byobu-select-backend
/usr/bin/byobu-select-backend
$ command -v tmux
/usr/bin/tmux
$ command -v screen
/usr/bin/screen
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1

Byobu can only use a backend that is installed. The selector's menu lists the choices it supports, but a missing tmux or screen command can still make the selected default unusable. If one command is absent, install it through your normal package-management process before choosing it. That separate installation may require elevated privileges; changing the Byobu preference does not.

2. Choose the default explicitly

Pass exactly one supported argument. To make new plain byobu launches use tmux:

$ byobu-select-backend tmux

The command is quiet and returns status 0 when it writes the preference. The equivalent Screen selection is:

$ byobu-select-backend screen
$ printf 'selector exit status: %s\n' "$?"
selector exit status: 0

Checkpoint: the last command shown should be the selector itself if you want to inspect its status. The printed status belongs to the command immediately before printf.

3. Verify the saved preference

The manual names ~/.byobu/backend as the configuration file. On this installed release, Byobu also follows its configuration-directory rules: an existing ~/.byobu is preferred; otherwise the backend file is under $XDG_CONFIG_HOME/byobu/backend, or ~/.config/byobu/backend when XDG_CONFIG_HOME is unset.

Ask the shell which directory this account uses, then display only the backend file:

$ if [ -n "$BYOBU_CONFIG_DIR" ]; then
>     config_dir="$BYOBU_CONFIG_DIR"
> elif [ -d "$HOME/.byobu" ]; then
>     config_dir="$HOME/.byobu"
> else
>     config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/byobu"
> fi
$ printf 'backend file: %s\n' "$config_dir/backend"
backend file: /home/you/.config/byobu/backend
$ cat "$config_dir/backend"
BYOBU_BACKEND=screen

The exact path depends on your account. The expected line is BYOBU_BACKEND=tmux or BYOBU_BACKEND=screen, matching the argument you supplied. Do not edit the file with a value other than those two documented backends.

4. Use the interactive menu when you prefer prompts

With no argument, the selector prompts for a choice. On this installation the menu defaults to tmux:

$ byobu-select-backend

Select the byobu backend:
  1. tmux
  2. screen

Choose 1-2 [1]:

Enter 1 for tmux or 2 for Screen, then press Enter. Pressing Enter without a number accepts the displayed tmux default. Invalid input causes the prompt to be shown again, so do not assume that a mistyped choice changed anything.

For scripts, use the explicit argument instead. It avoids a prompt waiting on standard input and makes the intended state visible in a review.

5. Keep one session on the other backend

The default is not a lock on every Byobu invocation. If you need to force a particular session, use the backend-specific helper named by the manual:

$ byobu-tmux
$ byobu-screen

These commands start Byobu through tmux or Screen for that invocation, regardless of the default preference. They are useful for testing a change or supporting an older session without repeatedly rewriting the default.

Do not run both helpers blindly against a production session. Starting a second terminal multiplexer can create a new session instead of attaching to the one you expected. Check the session list and your current terminal before closing anything. The selector itself does not terminate sessions, so there is no service-disruption rollback to perform after changing the default.

6. Switch back if a tool depends on the old backend

Changing the default is reversible. If a new byobu launch behaves differently from a script or team procedure, set the previous backend explicitly and verify the file again:

$ byobu-select-backend tmux
$ grep '^BYOBU_BACKEND=' "$config_dir/backend"
BYOBU_BACKEND=tmux

If config_dir is not still set in your shell, repeat step 3 or read the path printed by that step. Avoid using sudo to write a per-user preference: it can create or alter root's Byobu configuration instead of the account that will run byobu.

A failed selector invocation normally means the argument was not screen or tmux, or that the configuration directory cannot be written. Check the command spelling and ownership of the selected directory. Do not delete the whole .byobu directory as a repair; it may contain profiles, status settings and key bindings unrelated to the backend choice.