v0.51.0 (Breaking API deprecations)

Breaking Changes

Deprecate legacy APIs

Legacy API methods (deprecated in v0.16–v0.33) now raise DeprecatedError (hard error) instead of emitting DeprecationWarning.

See the migration guide for full context and examples.

• Deprecate legacy APIs (raise DeprecatedError) by @tony in #611

Method Renamings

Deprecated	Replacement	Class	Deprecated Since
kill_server()	kill()	Server	0.30.0
attach_session()	attach()	Session	0.30.0
kill_session()	kill()	Session	0.30.0
select_window()	select()	Window	0.30.0
kill_window()	kill()	Window	0.30.0
split_window()	split()	Window	0.33.0
select_pane()	select()	Pane	0.30.0
resize_pane()	resize()	Pane	0.28.0
split_window()	split()	Pane	0.33.0

Property Renamings

Deprecated	Replacement	Class	Deprecated Since
attached_window	active_window	Session	0.31.0
attached_pane	active_pane	Session	0.31.0
attached_pane	active_pane	Window	0.31.0

Query/Filter API Changes

Deprecated	Replacement	Class	Deprecated Since
list_sessions() / _list_sessions()	sessions property	Server	0.17.0
list_windows() / _list_windows()	windows property	Session	0.17.0
list_panes() / _list_panes()	panes property	Window	0.17.0
where({...})	.filter(**kwargs) on sessions/windows/panes	All	0.17.0
find_where({...})	.get(default=None, **kwargs) on sessions/windows/panes	All	0.17.0
get_by_id(id)	.get(session_id/window_id/pane_id=..., default=None)	All	0.16.0
children property	sessions/windows/panes	All	0.17.0

Attribute Access Changes

Deprecated	Replacement	Deprecated Since
obj['key']	obj.key	0.17.0
obj.get('key')	obj.key	0.17.0
obj.get('key', None)	getattr(obj, 'key', None)	0.17.0

Still Soft Deprecations (DeprecationWarning)

The following deprecations from v0.50.0 continue to emit DeprecationWarning only:

Deprecated	Replacement	Class
set_window_option()	set_option()	Window
show_window_option()	show_option()	Window
show_window_options()	show_options()	Window
g parameter	global_ parameter	Options & hooks methods

Migration Example

Before (deprecated, now raises DeprecatedError):

# Old method names
server.kill_server()
session.attach_session()
window.split_window()
pane.resize_pane()

# Old query API
server.list_sessions()
session.find_where({'window_name': 'main'})

# Old dict-style access
window['window_name']

After:

# New method names
server.kill()
session.attach()
window.split()
pane.resize()

# New query API
server.sessions
session.windows.get(window_name='main', default=None)

# New attribute access
window.window_name

Links

• API Documentation
• Migration Guide
• Changelog

Full Changelog: v0.50.1...v0.51.0

v0.50.1 - Maintenance release

Documentation

• Doc fixes by @tony in #612

Full Changelog: v0.50.0...v0.50.1

v0.50.0 - options and hook management

libtmux 0.50 brings a major enhancement to option and hook management with a unified, typed API for managing tmux options and hooks across all object types.

Highlights

• Unified Options API: New show_option(), show_options(), set_option(), and unset_option() methods available on Server, Session, Window, and Pane
• Hook Management: Full programmatic control over tmux hooks with support for indexed hook arrays and bulk operations
• SparseArray: New internal data structure for handling tmux's sparse indexed arrays (e.g., command-alias[0], command-alias[99])
• tmux 3.2+ baseline: Removed support for tmux versions below 3.2a, enabling cleaner code and full hook/option feature support

Unified Options API

All tmux objects now share a consistent options interface:

import libtmux

server = libtmux.Server()
session = server.sessions[0]
window = session.windows[0]

# Get all options as a structured dict
session.show_options()
# {'activity-action': 'other', 'base-index': 0, ...}

# Get a single option value
session.show_option('base-index')
# 0

# Set an option
window.set_option('automatic-rename', True)

# Unset an option (revert to default)
window.unset_option('automatic-rename')

Hook Management

Programmatic control over tmux hooks:

session = server.sessions[0]

# Set a hook
session.set_hook('session-renamed', 'display-message "Renamed!"')

# Get hook value (returns SparseArray for indexed hooks)
session.show_hook('session-renamed')
# {0: 'display-message "Renamed!"'}

# Get all hooks
session.show_hooks()

# Remove a hook
session.unset_hook('session-renamed')

# Bulk operations for indexed hooks
session.set_hooks('session-renamed', {
    0: 'display-message "Hook 0"',
    1: 'display-message "Hook 1"',
    5: 'run-shell "echo hook 5"',
})

Breaking Changes

Deprecated Window methods

The following methods are deprecated and will be removed in a future release:

Deprecated	Replacement
Window.set_window_option()	Window.set_option()
Window.show_window_option()	Window.show_option()
Window.show_window_options()	Window.show_options()

Deprecated g parameter

The g parameter for global options is deprecated in favor of global_:

# Before (deprecated)
session.show_option('status', g=True)

# After (0.50.0+)
session.show_option('status', global_=True)

New Constants

• OptionScope enum: Server, Session, Window, Pane
• OPTION_SCOPE_FLAG_MAP: Maps scope to tmux flags (-s, -w, -p)
• HOOK_SCOPE_FLAG_MAP: Maps scope to hook flags

Documentation

• New topic guide: Options and Hooks
• New topic guides: Automation patterns, Workspace setup, Pane interaction, QueryList filtering
• Refreshed README with hero section, quickstart, and more examples

tmux Version Compatibility

Feature	Minimum tmux
All options/hooks features	3.2+
Window/Pane hook scopes (-w, -p)	3.2+
client-active, window-resized hooks	3.3+
pane-title-changed hook	3.5+

What's Changed

• Improved option management, add hook management by @tony in #516
• Refresh README by @tony in #609

Full Changelog: v0.49.0...v0.50.0

v0.49.0 (drop tmux < 3.2)

What's Changed

Breaking: tmux <3.2 fully dropped

• Drop support for tmux versions < 3.2 by @tony in #608

Full Changelog: v0.48.0...v0.49.0

v0.48.0 (deprecating tmux <3.2)

What's Changed

Breaking: tmux <3.2 deprecated

Deprecate old tmux versions by @tony in #606

Development

tmux: Add tmux 3.6 to testgrid by @tony in #607

Full Changelog: v0.47.0...v0.48.0

v0.47.0 - Drop Python 3.9

Breaking changes

• Support Python 3.14 by @tony in #601
• Drop Python 3.9 by @tony in #602

Full Changelog: v0.46.2...v0.47.0

v0.46.2 - `start_directory` typing fix

What's Changed

• Fix new_window argument typing in Session by @Data5tream in #596
  • types: Add StrPath typing, fix new_session by @tony in #597
    • types: Add StrPath typing, fix new_session, part 2 by @tony in #598

New Contributors

• @Data5tream made their first contribution in #596

Full Changelog: v0.46.1...v0.46.2

v0.46.1 - Maintenance release

Full Changelog: v0.46.0...v0.46.1

Changes

Feature branch at v0.46.x

v0.46.x will extend the life of v0.46.0 while new features are being developed for watching for changes within libtmux panes, windows, and sessions.

See:

• #587
• #582

Documentation

• Fix typo in Pane.send_keys (#593)

  Thank you @subbyte!

v0.46.0 - Internal improvements

Breaking Changes

• Test Helper Imports Refactored: Direct imports from libtmux.test are no longer possible. You must now import from specific submodules (#580)

  # Before:
  from libtmux.test import namer
  # After: 
  from libtmux.test.named import namer

  # Before:
  from libtmux.test import RETRY_INTERVAL_SECONDS
  # After: 
  from libtmux.test.constants import RETRY_INTERVAL_SECONDS

Internal Improvements

• Enhanced Test Utilities: The EnvironmentVarGuard now handles variable cleanup more reliably
• Comprehensive Test Coverage: Added test suites for constants and environment utilities
• Code Quality: Added proper coverage markers to exclude type checking blocks from coverage reports
• Documentation: Improved docstrings and examples in the random module

These changes improve maintainability of test helpers both internally and for downstream packages that depend on libtmux.

What's Changed

• Coverage: Test helpers by @tony in #580

Full Changelog: v0.45.0...v0.46.0

v0.45.0 - test helpers overhaul

What's Changed

Breaking Changes

Test helpers: Refactor

by @tony in #578

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

Misc

• Cursor rules: Add Cursor Rules for Development and Git Commit Standards by @tony in #575

CI

• tests(ci) Check runtime deps import correctly by @tony in #574

Full Changelog: v0.44.2...v0.45.0