Literal text and tmux formats

tmux expands formats such as #{session_name} in many command arguments, including window names, pane titles and start directories. libtmux keeps the text you pass as plain str exactly as you typed it, so a # in a name or path never turns into something else. When you want tmux to expand a value, wrap it in Format.

>>> from libtmux import Format

Plain strings are kept as typed

A plain str is stored exactly, even when it looks like a format:

>>> window.rename_window("build#2")
Window(...)
>>> window.window_name
'build#2'

>>> window.rename_window("#{session_name}")
Window(...)
>>> window.window_name
'#{session_name}'

This covers every name, title, start directory and file path libtmux passes to an argument tmux expands:

Ask tmux to expand a value

Wrap a format your program wrote in Format, and tmux expands it as it would in tmux.conf:

>>> pane.split(start_directory=Format("#{pane_current_path}"))
Pane(...)

Each argument decides for itself, so one call can mix the two. Here the window name stays literal while the start directory is expanded:

>>> new_window = session.new_window(
...     window_name="build#2",
...     start_directory=Format("#{pane_current_path}"),
... )
>>> new_window.window_name
'build#2'

Type checkers see the difference too. Parameters that accept a format are typed str | Format, so passing a Format where tmux would store the text unchanged, such as Pane.break_pane(window_name=...), is a type error.

Note

tmux expands a start directory against the session’s active pane, not the pane being split, so #{pane_current_path} is the active pane’s directory. To start in a particular pane’s directory, pass its pane_current_path instead.

Add text from users or files

Only wrap text your program wrote. Text from users, files or other programs can contain # too, so add it with + or join(), which keep it literal:

>>> user_text = "50% #1"
>>> window.rename_window(Format("#{session_name}: ") + user_text)
Window(...)
>>> window.window_name == f"{session.session_name}: 50% #1"
True

Plain text can only be added where tmux reads text. Adding it after a format that ends with # or an unfinished % time field, or inside an unfinished #{...}, #(...) or #[...], raises, because tmux would read it as format syntax:

>>> Format("#{?pane_active,") + "yes"
Traceback (most recent call last):
...
ValueError: cannot add plain text to Format('#{?pane_active,'): ...

To place text inside an expression, such as one side of a comparison, use Format.escape(). It writes the text so tmux reads every character back as itself, including the , and } that would otherwise end an argument:

>>> same_name = (
...     Format("#{==:#{window_name},")
...     + Format.escape(window.window_name)
...     + Format("}")
... )
>>> window.active_pane.display_message(same_name, get_text=True)
['1']

Do not place text from users inside #(...). tmux finds the end of the command by counting parentheses before the shell sees any quoting, so a ) in the text ends the command early. Run the command from Python and pass its output instead.

Arguments tmux always expands

Some arguments are formats by design: display_message(), the commands of run_shell(), if_shell() and pipe(), and the filter of the search_* methods. A plain str there reaches tmux as written and is expanded, as it always has been:

>>> pane.display_message("#{pane_id}", get_text=True) == [pane.pane_id]
True

They accept a Format too, so text from users can be shown exactly. Some of them also expand % as a time field, which Format.escape() keeps literal:

>>> pane.display_message(Format.escape("50%d done"), get_text=True)
['50%d done']

Menu item names given to display_menu() are formats as well, so a name such as #{?pane_marked,Unmark,Mark} changes with the pane.

What literal means for titles

A literal title is not expanded as a format. tmux still reads #[...] style sequences when it draws a title on screen, as it does for every name it draws, so a title of #[fg=red]X is shown as a red X.

Version notes

  • tmux expands run_shell()’s cwd from tmux 3.8. On earlier tmux a plain path is used as given, and cwd=Format(...) raises LibTmuxException.

  • save_buffer() takes a plain path only: libtmux creates the file readable by its owner before tmux writes it, which needs the final path.

  • new_session() with kill_session=True needs a plain session name, because a Format name is known only after tmux creates the session.

Raw commands

Server.cmd() and the other cmd() methods pass arguments to tmux unchanged, so a # there is expanded as tmux sees fit.