Save and Restore tmux Panes with byobu-layout

byobu-layout saves the pane arrangement of your current Byobu-tmux window under a name you choose. So a hard-won three-pane split survives a reattach or a fat-fingered close. The work takes about five minutes if Byobu is already running. This guide covers the Byobu 6.11 package installed on Ubuntu, with tmux 3.4. The command does not work with Byobu backed by GNU Screen.

What byobu-layout changes

byobu-layout records the active tmux window's pane arrangement and saves it in your Byobu configuration directory. A saved layout is a small per-user file, not a copy of the commands or data running in each pane. Restoring it changes the pane arrangement in the current tmux window.

The basic form is:

byobu-layout save NAME
byobu-layout restore NAME

NAME is your label, such as ops-three-pane. There is no separate option syntax and no need for sudo. Run the command as the user who owns the Byobu session.

1. Check that Byobu is using tmux

Start or attach to a tmux-backed Byobu session. To force a new session to use tmux, use:

byobu-tmux

If plain byobu keeps starting Screen, set tmux as the default for future plain byobu launches:

byobu-select-backend tmux

This changes the default, not an already running session, so start or attach to a tmux session afterwards. The installed package on this machine is Byobu 6.11 and the installed tmux is 3.4. The manpage's explicit boundary is the important part: a Screen-backed Byobu session cannot use this layout utility.

2. Arrange the panes you want to keep

Create or resize panes in the active Byobu window until they show the work you want, for example a shell on the left and two stacked shells on the right. Layouts describe pane geometry, not pane contents, working directories or running processes.

Before saving, confirm that tmux can see the current panes:

tmux list-panes

You should see one line per pane. The exact identifiers and dimensions depend on your window. If this says that no tmux server is running, you are not operating inside the expected Byobu-tmux session: reattach to the session and try again.

3. Save a named layout

Choose a name with no spaces. This example writes a layout called ops-three-pane:

byobu-layout save ops-three-pane

The command normally prints nothing when it succeeds. It creates the layouts directory if needed. With the standard Ubuntu 6.11 layout, the file is under ~/.config/byobu/layouts/ unless you already have ~/.byobu/ or have set BYOBU_CONFIG_DIR.

Verify the file without changing it:

layout_dir="${BYOBU_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/byobu}/layouts"
ls -l "$layout_dir/ops-three-pane"
sed -n '1,2p' "$layout_dir/ops-three-pane"

The first line is the number of panes saved; the second is tmux's layout string. Treat this file as data managed by Byobu. Do not edit the layout string by hand unless you have a specific tmux layout to test.

4. Restore it after a change

To apply the saved arrangement to the current Byobu-tmux window, run:

byobu-layout restore ops-three-pane

Byobu creates additional panes when the saved layout needs more than the current window has, then selects the saved tmux layout. It does not recreate the shell state that was in those panes: any newly created pane starts according to your tmux and Byobu configuration.

byobu-layout save before-experiment
byobu-layout restore ops-three-pane

To undo that test, restore the backup:

byobu-layout restore before-experiment

Preset layouts and interactive mode

The installed utility also accepts list, which displays the built-in tmux presets and your saved files:

byobu-layout list

Presets include even-horizontal, even-vertical, main-horizontal, main-vertical and tiled. Apply one directly, without saving it first:

byobu-layout restore tiled

• Omit the name and the utility goes interactive: saving prompts for a unique name, restoring presents a numbered list. Useful at a terminal, but named commands are easier to repeat in notes and scripts.

The manpage documents the save and restore actions. The list action and the preset names are behaviour of the installed Byobu 6.11 script, so check locally before relying on them on another distribution or a different package version.

Common traps

• Screen backend. The utility calls tmux commands directly. Switch Byobu to tmux before using it.
• Wrong window. Save and restore operate on the current tmux window. Select the intended Byobu window first.
• Name collision. Saving over an existing name replaces that layout file. Use a new name when you need a recoverable copy.
• Missing name. Restoring an unknown name treats it as a tmux layout string. This can fail or apply an unintended arrangement, so prefer a name shown by byobu-layout list.
• Expecting application recovery. The layout does not save files, commands, scrollback or working directories.