Set Byobu Colours Safely with byobu-select-profile

You will finish with a repeatable way to list Byobu's built-in colour profiles, change the foreground or background, and choose deterministic or random colours when your backend supports them. The examples match byobu 6.11-0ubuntu1.1 installed on Ubuntu 24.04 here.

Allow about ten minutes. You need an ordinary shell and an existing Byobu installation. These commands normally run as your login user. Do not use sudo: the utility changes your user configuration and needs to reload your user session, not the system copy of Byobu.

1. Check the installed command

Confirm which executable will run and record the package version. This is read-only and does not need elevated privileges:

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

Your package version may differ. The installed manpage documents the same option set checked here: --list, --background, --foreground, --hostname, --ip and --random. The command has no interactive menu in this version, so an option must be supplied.

2. List the available profiles

Start with the list. It is harmless and does not select a profile:

$ byobu-select-profile --list
default_light
default_dark
white
black
grey
dark_grey
light_grey
blue
light_blue
cyan
light_cyan
green
light_green
purple
light_purple
red
light_red
yellow
brown

The output is one profile name per line. This local 6.11 script has the names above; another release can add or remove names. Treat the output from your own machine as authoritative.

The word profile is slightly misleading here. --list reports colour names, while the utility writes Byobu's colour settings and reloads the current backend. It is not selecting an unrelated terminal profile or changing your shell prompt.

3. Set a foreground or background colour

Run the command inside an active Byobu session so the change can be reloaded immediately. Pick one of the names printed by --list:

$ byobu-select-profile --background dark_grey
$ byobu-select-profile --foreground light_grey

Short options are available as -b and -f. The argument is a colour name, not a shell colour number or a quoted sentence. The command returns to the prompt without a success message when the operation completes, so check the exit status if you are scripting it:

$ byobu-select-profile --background blue
$ printf 'exit status: %s\n' "$?"
exit status: 0

These options change the per-user Byobu configuration. In the installed version, the script stores the screen colour values in the Byobu configuration directory and marks the runtime state for reload. The directory is normally ~/.byobu when that directory already exists, otherwise $XDG_CONFIG_HOME/byobu or ~/.config/byobu.

4. Use host-based or random colours deliberately

The remaining choices calculate a tmux colour rather than selecting one of the named profiles:

$ byobu-select-profile --hostname
$ byobu-select-profile --ip
$ byobu-select-profile --random

--hostname hashes the local hostname, so the same host should normally receive the same result. --ip hashes the address selected by Byobu's installed IP helper, so it can change when the machine's network changes. --random draws bytes from the system random device, so each run can produce a different result.

In this installed script these three operations call tmux colour settings and warn that the functionality is only supported with the tmux backend. They are therefore poor choices for a portable shell script unless you have already confirmed that Byobu is using tmux. A random colour can also make contrast less predictable, which is a practical accessibility problem on a shared or recorded terminal.

5. Check the result in the session

Look at a live Byobu status bar after a change. For a script or a remote session where visual inspection is inconvenient, retain the command's exit status and inspect the user configuration rather than guessing:

$ printf 'Byobu configuration candidates:\n'
$ for path in "$HOME/.byobu/color" "${XDG_CONFIG_HOME:-$HOME/.config}/byobu/color"; do
>     if [ -r "$path" ]; then
>         printf '%s\n' "$path"
>         sed -n '1,5p' "$path"
>     fi
> done
Byobu configuration candidates:
/home/alice/.config/byobu/color
FOREGROUND=W
BACKGROUND=b
MONOCHROME=0

The path and one-letter values are implementation details of this package, and your values will differ. The useful check is that the file exists in the directory selected by your installation and contains foreground and background settings. If no file appears, check that the command was run as the same user who owns the Byobu session.

6. Avoid the common traps

• Do not pass an arbitrary colour such as orange and assume it is supported. Use --list first; unknown names fall back to the script's default mapping rather than giving you a reliable custom colour.
• Do not confuse --foreground and --background. Test one at a time and keep a note of the previous setting if you are changing a shared working environment.
• Do not run these commands with sudo. Root would edit root's Byobu configuration and may still be unable to reload your user session.
• Do not treat a zero exit status as proof that a remote terminal can display every colour. Terminal capability and contrast still depend on the terminal emulator and its colour scheme.