Migration notes¶

Migration and deprecation notes for libtmux are here, see Changelog as well.

Welcome on board! 👋

📌 For safety, always pin the package
📖 Check the migration notes (You are here)
📣 If you feel something got deprecated and it interrupted you - past, present, or future - voice your opinion on the tracker.

We want to make libtmux fun, reliable, and useful for users.

API changes can be painful.

If we can do something to draw the sting, we’ll do it. We’re taking a balanced approach. That’s why these notes are here!

(Please pin the package. 🙏)

Upcoming Release¶

Detailed migration steps for the next version will be posted here.

libtmux 0.46.0 (2025-02-25)¶

Imports removed from libtmux.test (#580)¶

Root-level of imports from libtmux.test are no longer possible.

# Before 0.46.0
from libtmux.test import namer

# From 0.46.0 onward
from libtmux.test.named import namer

Same thing with constants:

# Before 0.46.0
from libtmux.test import (
  RETRY_INTERVAL_SECONDS,
  RETRY_TIMEOUT_SECONDS,
  TEST_SESSION_PREFIX
)

# From 0.46.0 onward
from libtmux.test.constants import (
  RETRY_INTERVAL_SECONDS,
  RETRY_TIMEOUT_SECONDS,
  TEST_SESSION_PREFIX
)

libtmux 0.45.0 (2025-02-23)¶

Test helpers: Module moves¶

Test helper functionality has been split into focused modules (#578):

libtmux.test module split into:
- libtmux.test.constants: Test-related constants (TEST_SESSION_PREFIX, etc.)
- libtmux.test.environment: Environment variable mocking
- libtmux.test.random: Random string generation utilities
- libtmux.test.temporary: Temporary session/window management

Breaking: Import paths have changed. Update imports:

# Old (0.44.x and earlier)
from libtmux.test import (
    TEST_SESSION_PREFIX,
    get_test_session_name,
    get_test_window_name,
    namer,
    temp_session,
    temp_window,
    EnvironmentVarGuard,
)

# New (0.45.0+)
from libtmux.test.constants import TEST_SESSION_PREFIX
from libtmux.test.environment import EnvironmentVarGuard
from libtmux.test.random import get_test_session_name, get_test_window_name, namer
from libtmux.test.temporary import temp_session, temp_window

0.35.0: Commands require explicit targets (2024-03-17)¶

Commands require explicit targets (#535)¶

Server.cmd(), Session.cmd(), Window.cmd(), Pane.cmd() require passing target instead of ['-t', target], ['-tTargetName'], etc. This change is to avoid issues mistakenly interpreting -t in other shell values as targets.

Before:
```
session.cmd('send-keys', 'echo hello', '-t', '0')
```
With 0.35.0 and after:
```
session.cmd('send-keys', 'echo hello', target='0')
```

0.33.0: Deprecations for splitting (2024-03-03)¶

Deprecations (#532)¶

Window.split_window() to Window.split()
Pane.split_window() to Pane.split()

0.31.0: Renaming and command cleanup (2024-02-17)¶

Cleanups (#527)¶

Commands: Param change

Server.cmd(), Session.cmd(), Window.cmd(), Pane.cmd()
- Use cmd: str as first positional
- Removed unused keyword arguments **kwargs

Renamings (#527)¶

Session.attached_window renamed to Session.active_window()
- Session.attached_window deprecated
Session.attached_pane renamed to Session.active_pane()
- Session.attached_pane deprecated
Window.attached_pane renamed to Window.active_pane()
- Window.attached_pane deprecated

0.28.0: Resizing and detached by default (2024-02-15)¶

Detach by default¶

Session.new_window() + Window.split_window() no longer attaches by default (#523)
- 0.28.0 and greater: Defaults to attach=False.
- 0.27.1 and below: Defaults to attach=True.
For the old behavior in 0.28.0 and beyond, pass attach=True explicitly.

Resizing panes¶

Pane.resize_pane() renamed to Pane.resize() (via #523)

This convention will be more consistent with Window.resize().

Pane.resize_pane()’s params changed (#523)

No longer accepts -U, -D, -L, -R directly, instead accepts ResizeAdjustmentDirection (see below).

0.27.1 and below: pane.resize_pane("-D", 20), pane.resize_pane("-R", 20)

0.28.0 and beyond:

from libtmux.constants import ResizeAdjustmentDirection
pane.resize_pane(adjustment_direction=ResizeAdjustmentDirection.Down, adjustment=25)
pane.resize_pane(
  adjustment_direction=ResizeAdjustmentDirection.Right, adjustment=25
)

0.17.0: Simplified attributes (2022-12-26)¶

Finding objects / relations¶

0.16 and below: session._windows(), session.list_windows(), etc.

0.17 and after: session.windows
0.16 and below: session.find_where({'window_name': my_window})

0.17 and after: session.windows.get(window_name=my_window, default=None)
- If not found and not default, raises ObjectDoesNotExist
- If multiple objects found, raises MultipleObjectsReturned
0.16 and below: session.where({'window_name': my_window})

0.17 and after: session.windows.filter(window_name=my_window)

Accessing attributes¶

0.16 and below: window['id']

0.17 and after: window.id
0.16 and below: window.get('id')

0.17 and after: window.id
0.16 and below: window.get('id', None)

0.17 and after: getattr(window, 'id', None)