Migration notes

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

Welcome on board! 👋

  1. 📌 For safety, always pin the package

  2. 📖 Check the migration notes (You are here)

  3. 📣 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.

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)

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

Cleanups (#527)

Renamings (#527)

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

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)