Question
tmux-resurrect pane layout limits during terminal dimension changes
Rahul Echo
0 reputation · 19 Aug 2021, 18:34 UTC
133.4K views1
Loading…
0 reputation · 19 Aug 2021, 18:34 UTC
tmux does not natively persist sessions across system reboots, necessitating the use of plugins like tmux-resurrect to save window and pane configurations to disk. While these tools can restore the structural shell state and current working directories, they do not capture the execution state of running processes.
A challenge arises when restoring a saved session into a terminal emulator with different dimensions than those present during the backup. Because tmux manages pane splits based on specific percentages or cell counts, changes in the host window size can lead to unexpected layout shifts or failure to render the original geometry correctly.
35275 reputation · 19 Aug 2021, 23:55 UTC
tmux-resurrect prioritizes the saved layout geometry—typically stored as relative percentages or split positions—but it is ultimately bound by the physical constraints of the active terminal emulator. When a session is restored, tmux attempts to map the saved coordinates onto the current available grid. If the terminal window is smaller than the saved configuration, tmux cannot force the original geometry to render.
When the current terminal is smaller than the minimum required size for the saved pane configuration, the following behaviors occur:
To minimize layout shifts when switching between terminal environments, follow these practices:
tmuxtmux-resurrect S.tmux.conf focuses on relative splits rather than fixed cell counts. This allows tmux to scale the layout proportionally across different resolutions.Ctrl-b + Space (the default layout cycle command) to force tmux to re-calculate pane boundaries based on the current dimensions.This analysis assumes you are using the standard tmux-resurrect plugin. There is uncertainty regarding how specific versions of tmux handle the "minimum cell width" constraint during a rapid resize; in some edge cases, resizing the window during the restoration process can cause the plugin to lose the layout string entirely.
Diagnostic Question: Are you experiencing the layout shift immediately upon restoration, or does it happen when you manually resize the window after the session has loaded?
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 19 Aug 2021, 22:45 UTC
The existing answer notes percentage-based layouts, but tmux-resurrect actually saves the raw tmux layout string (from #{window_layout}), which encodes pane dimensions as absolute cell counts, not relative percentages. This distinction matters because tmux's layout engine reapplies those exact cell counts against the current window size at restore time.
Restores run detached (no client attached), so the window size used is tmux's default (typically 80×24) or the session's size at creation—not your current terminal. Layouts are then recalculated when you attach, which is where the visible shift occurs.
tmux-resurrect S~/.tmux/resurrect/last (or the timestamped file) and note the window_layout values—they are cell counts.tmux list-panes -F '#{pane_width}x#{pane_height}' before and after.Also check show-options -g window-size (tmux 3.2+) and aggressive-resize; they control how windows adapt to client size changes after attach.