Keep Byobu on GNU Screen with byobu-screen

byobu-screen launches Byobu on GNU Screen instead of tmux, useful when a host's tooling or your own workflow is built around Screen. This guide gets you running, checks which session exists, covers a clean detach and reconnect, and shows how to pass a Screen option through. Allow about fifteen minutes for a first run. It uses Ubuntu's installed Byobu 6.11 with GNU Screen 4.09.01; the exact status-line appearance can vary with your terminal and user configuration.

You need a login shell, a usable terminal, and the byobu package. The normal commands are unprivileged. Do not start Byobu with sudo just to get a shell: it can create root-owned files in your home directory, and the installed wrapper refuses to run when the current user does not own $HOME.

1. Confirm the wrapper and backend

Check the executable, package version and underlying Screen version before trusting any example below:

$ command -v byobu-screen
/usr/bin/byobu-screen
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1
$ screen -v
Screen version 4.09.01 (GNU) 20-Aug-23

byobu-screen is a launcher, not a second window manager. Its manpage describes it as launching byobu with Screen, and the installed script selects the Screen backend from the command name itself. That is useful on a host where plain byobu would select tmux, or where your existing workflow is built around Screen.

2. Start a Screen-backed Byobu session

Run the wrapper with no arguments from a real terminal:

$ byobu-screen

• You should land in a shell inside a Byobu session, with Screen windows and Byobu status information at the bottom.
• The first run may create user configuration below $HOME/.byobu, unless $XDG_CONFIG_HOME is defined, in which case Byobu uses $XDG_CONFIG_HOME/byobu. Normal user state, not a system-wide change.
• The launcher normally uses a Screen session named byobu. If a matching session already exists, the wrapper hands control to Byobu's session selector rather than blindly creating another one.

That last point matters on a remote connection: check the list before starting a second shell.

$ byobu-screen -ls
There is a screen on:
        12345.byobu    (Detached)
1 Socket in /run/screen/S-alice.

The number and socket path are host-specific. With no sessions, the installed command reports No Sockets found and returns a non-zero status: an empty list, not evidence that the package is missing.

3. Detach and reconnect without losing work

Inside Byobu, press F6 to detach from the current Screen session. The programs in its windows keep running: this is the normal way to leave an SSH connection without killing a long-running command.

Reconnect with:

$ byobu-screen -r

If there is exactly one detached session, Screen reattaches it directly. If your terminal or keyboard does not send F6 reliably, the Screen command prefix is normally Ctrl-a; the Byobu manpage also documents Ctrl-a d as the traditional Screen detach action. Press the prefix, release it, then press d.

If Screen says the session is attached elsewhere, do not force a detach while another operator may be using it. Identify the session first:

$ byobu-screen -d -r 12345.byobu

4. Pass a Screen option without changing the backend

Arguments supplied to byobu-screen pass straight through to GNU Screen. For example, list sessions without attaching:

$ byobu-screen -list
No Sockets found in /run/screen/S-alice.

To give a session a private name, use Screen's -S option when starting it in a terminal:

$ byobu-screen -S project-shell

Use a name that means something on the host, and quote it if it contains shell metacharacters. The wrapper recognises session-related Screen options such as -S, -r and -d, so it does not force its default session name over your explicit choice. Verify the result with byobu-screen -ls.

5. Put repeatable windows in configuration

For a stable set of windows, create a user-owned file named windows in the Byobu configuration directory. Under Screen, each line uses Screen's window syntax. A minimal example:

$ config_dir="${XDG_CONFIG_HOME:+$XDG_CONFIG_HOME/byobu}"
$ config_dir="${config_dir:-$HOME/.byobu}"
$ mkdir -p "$config_dir"
$ printf '%s\n' 'screen -t shell bash' 'screen -t logs tail -f /path/to/application.log' > "$config_dir/windows"
$ byobu-screen

Replace /path/to/application.log with a real, readable log. This changes only your Byobu configuration and starts a log-following window; it does not install or restart a service. To undo it, remove the added line or restore your previous windows file before the next launch. Do not put passwords, private keys or commands with unreviewed shell expansions into this file.

For several named layouts, use files such as windows.project and select one with BYOBU_WINDOWS=project byobu-screen. The variable selects the Screen window set; it is not a session name. Keep the selected file under the same configuration directory and verify its commands before launching.

Common traps

• It launches tmux. You used byobu, not byobu-screen. Start the explicit wrapper, or inspect $XDG_CONFIG_HOME/byobu/backend and $HOME/.byobu/backend before changing the generic default.
• The command refuses to run under sudo. Return to the original user and run it there. If elevated access is genuinely required, the manpage says to use sudo -H, but a separate root-owned Byobu environment is usually the wrong place for an ordinary user session.
• Colours or function keys look wrong. Check the terminal type and locale, then try a normal UTF-8 terminal. The Byobu manpage records compatibility issues with old Screen builds, PuTTY function-key settings and non-UTF-8 locales. Do not alter a shared server's terminal configuration without checking who depends on it.
• There are too many open files or processes. Inspect ulimit -a and ask the system administrator to review the limits. Raising limits blindly can affect other workloads.