# libtmux

> Typed Python API for tmux. Control servers, sessions, windows, and panes as Python objects.

## Documentation

- [Quickstart](https://libtmux.git-pull.com/quickstart/): libtmux allows for developers and system administrators to control live tmux sessions using python code.
- [Topics](https://libtmux.git-pull.com/topics/): Explore libtmux’s core functionalities and underlying principles at a high level, while providing essential context and detailed explanations to help you understand its design and usage.
- [API Reference](https://libtmux.git-pull.com/api/): libtmux’s public API mirrors tmux’s object hierarchy: Server → Session → Window → Pane. Attached terminals show up as Client objects accessed off the server.
- [Testing Utilities](https://libtmux.git-pull.com/api/testing/): Tools for testing code that uses libtmux.
- [Internals](https://libtmux.git-pull.com/internals/): Typed dataclass utilities used across internal modules.
- [Project](https://libtmux.git-pull.com/project/): Project guides, compatibility information, and API governance.
- [Changelog](https://libtmux.git-pull.com/history/): For instructions on installing the development version of libtmux, refer to development releases.
- [Migration notes](https://libtmux.git-pull.com/migration/): Migration and deprecation notes for libtmux are here, see changelog as well.
- [Glossary](https://libtmux.git-pull.com/glossary/): A tool to manage workspaces with tmux. A pythonic abstraction of tmux.

## Documentation

- [Clients](https://libtmux.git-pull.com/api/libtmux.client/): Attached terminals connected to a tmux server
- [Utilities](https://libtmux.git-pull.com/api/libtmux.common/): Helper methods and mixins for libtmux.
- [Constants](https://libtmux.git-pull.com/api/libtmux.constants/): Constant variables for libtmux.
- [Exceptions](https://libtmux.git-pull.com/api/libtmux.exc/): libtmux exceptions.
- [Hooks](https://libtmux.git-pull.com/api/libtmux.hooks/): Helpers for tmux hooks.
- [Properties](https://libtmux.git-pull.com/api/libtmux.neo/): Get access to the data attributes behind tmux sessions, windows and panes.
- [Options](https://libtmux.git-pull.com/api/libtmux.options/): Helpers for tmux options.
- [Panes](https://libtmux.git-pull.com/api/libtmux.pane/): Contain pseudoterminals (pty(4))
- [Servers](https://libtmux.git-pull.com/api/libtmux.server/): Identified by socket path and socket name
- [Sessions](https://libtmux.git-pull.com/api/libtmux.session/): Exist inside Servers
- [Windows](https://libtmux.git-pull.com/api/libtmux.window/): Exist inside Sessions
- [Fixtures](https://libtmux.git-pull.com/api/testing/pytest-plugin/fixtures/): Add a fixture name as a test parameter — pytest creates and injects it automatically. You never call fixtures yourself.
- [pytest Plugin](https://libtmux.git-pull.com/api/testing/pytest-plugin/): libtmux’s pytest plugin provides fixtures for isolated tmux servers, sessions, windows, and panes in automated tests.
- [Usage Guide](https://libtmux.git-pull.com/api/testing/pytest-plugin/usage/): libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an independent tmux server.
- [Constants](https://libtmux.git-pull.com/api/testing/test-helpers/constants/): Test-related constants used across libtmux test helpers.
- [Environment](https://libtmux.git-pull.com/api/testing/test-helpers/environment/): Environment variable mocking utilities for tests.
- [Test Helpers](https://libtmux.git-pull.com/api/testing/test-helpers/): Utilities for writing reliable tests against libtmux and downstream code that uses tmux.
- [Random](https://libtmux.git-pull.com/api/testing/test-helpers/random/): Random string generation utilities for test names.
- [Retry Utilities](https://libtmux.git-pull.com/api/testing/test-helpers/retry/): Retry helper functions for libtmux test utilities. These utilities help manage testing operations that may require multiple attempts before succeeding.
- [Temporary Objects](https://libtmux.git-pull.com/api/testing/test-helpers/temporary/): Context managers for temporary tmux objects (sessions, windows).
- [Internal Constants - libtmux._internal.constants](https://libtmux.git-pull.com/internals/api/libtmux._internal.constants/): Internal constants.
- [Dataclass helpers - libtmux._internal.dataclasses](https://libtmux.git-pull.com/internals/api/libtmux._internal.dataclasses/): dataclasses utilities.
- [List querying - libtmux._internal.query_list](https://libtmux.git-pull.com/internals/api/libtmux._internal.query_list/): Utilities for filtering or searching list of objects / list data.
- [Internal Sparse Array - libtmux._internal.sparse_array](https://libtmux.git-pull.com/internals/api/libtmux._internal.sparse_array/): Sparse array for libtmux options and hooks.
- [Code Style](https://libtmux.git-pull.com/project/code-style/): libtmux uses ruff for both linting and formatting.
- [Compatibility](https://libtmux.git-pull.com/project/compatibility/): Minimum: Python 3.10
- [Development](https://libtmux.git-pull.com/project/contributing/): Install git and uv
- [Deprecations](https://libtmux.git-pull.com/project/deprecations/): Active deprecations with timeline and migration paths.
- [Public API](https://libtmux.git-pull.com/project/public-api/): Every module documented under API Reference is public API. This includes:
- [Releasing](https://libtmux.git-pull.com/project/releasing/): libtmux is pre-1.0. Minor version bumps may include breaking API changes. Users should pin to >=0.x,<0.y.
- [Architecture](https://libtmux.git-pull.com/topics/architecture/): libtmux is a typed abstraction layer for tmux. It builds upon tmux’s concept of targets (-t) to direct commands against individual sessions, windows, and panes, and FORMATS — template variables tmu...
- [Automation Patterns](https://libtmux.git-pull.com/topics/automation_patterns/): libtmux is ideal for automating terminal workflows, orchestrating multiple processes, and building agentic systems that interact with terminal applications. This guide covers practical patterns for...
- [Clients](https://libtmux.git-pull.com/topics/clients/): A tmux Client is an attached terminal — the side of the tmux connection a user sees. The same tmux server can host many clients at once (one per $ tmux attach from different terminals), and each cl...
- [Configuration](https://libtmux.git-pull.com/topics/configuration/): libtmux itself does not read environment variables for configuration. All configuration is done programmatically through the Python API.
- [Context Managers](https://libtmux.git-pull.com/topics/context_managers/): libtmux provides context managers for all main tmux objects to ensure proper cleanup of resources. This is done through Python’s with statement, which automatically handles cleanup when you’re done...
- [Design Decisions](https://libtmux.git-pull.com/topics/design-decisions/): tmux organizes terminals in a strict hierarchy: Server → Session → Window → Pane. Each level owns the next. libtmux mirrors this with Python objects that maintain the same parent-child relationships.
- [QueryList Filtering](https://libtmux.git-pull.com/topics/filtering/): libtmux uses QueryList to enable Django-style filtering on tmux objects. Every collection (server.sessions, session.windows, window.panes) returns a QueryList, letting you filter sessions, windows,...
- [Format-Token Fields](https://libtmux.git-pull.com/topics/format-tokens/): Every libtmux object — Server, Session, Window, Pane, Client — exposes a flat set of typed string attributes named after tmux’s FORMATS tokens (pane_id, window_zoomed_flag, client_theme, etc.). Thi...
- [Options and Hooks](https://libtmux.git-pull.com/topics/options_and_hooks/): libtmux provides a unified API for managing tmux options and hooks across all object types (Server, Session, Window, Pane).
- [Pane Interaction](https://libtmux.git-pull.com/topics/pane_interaction/): libtmux provides powerful methods for interacting with tmux panes programmatically. This is especially useful for automation, testing, and orchestrating terminal-based workflows.
- [Public vs Internal API](https://libtmux.git-pull.com/topics/public-vs-internal/): libtmux draws a clear line between public and internal code:
- [Traversal](https://libtmux.git-pull.com/topics/traversal/): libtmux provides convenient access to move around the hierarchy of sessions, windows and panes in tmux.
- [Workspace Setup](https://libtmux.git-pull.com/topics/workspace_setup/): libtmux makes it easy to create and configure multi-pane workspaces programmatically. This is useful for setting up development environments, running parallel tasks, and orchestrating terminal-base...