# 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. In doctests, libtmux injects the same objects through doctest_namespace:
- [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](https://libtmux.git-pull.com/internals/api/libtmux._internal.constants/): The libtmux._internal.constants module documents private constants used inside libtmux.
- [Dataclass helpers](https://libtmux.git-pull.com/internals/api/libtmux._internal.dataclasses/): The libtmux._internal.dataclasses module contains private dataclass utilities used by internal objects.
- [List querying](https://libtmux.git-pull.com/internals/api/libtmux._internal.query_list/): The libtmux._internal.query_list module contains the private collection filtering implementation behind public list accessors.
- [Internal Sparse Array](https://libtmux.git-pull.com/internals/api/libtmux._internal.sparse_array/): The libtmux._internal.sparse_array module contains the sparse-index mapping used by indexed hooks and options.
- [Code Style](https://libtmux.git-pull.com/project/code-style/): This page’s content moved. Formatting, linting, typing, and import conventions are now in Contributing. Docstring conventions are in .github/WRITING.md.
- [Compatibility](https://libtmux.git-pull.com/project/compatibility/): Minimum: Python 3.10
- [Contributing](https://libtmux.git-pull.com/project/contributing/): The contributor guide — environment setup, the gates, tests, documentation builds, releases, and the pull request process — now lives in .github/CONTRIBUTING.md.
- [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/): When you use libtmux, you work through a hierarchy of typed Python objects — Server, Session, Window, and Pane — each a proxy for the tmux entity it represents. You navigate from one to the next (a...
- [Automation patterns](https://libtmux.git-pull.com/topics/automation_patterns/): When you automate a terminal workflow, you are usually coordinating more than one process: you kick off work in one pane, watch another for a completion signal, and keep several tasks moving withou...
- [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/): You configure libtmux through Python: there are no config files, and you set everything through method calls on Server, Session, Window, and Pane objects, with sensible defaults. If you’re driving ...
- [Context managers](https://libtmux.git-pull.com/topics/context_managers/): When you create tmux objects through libtmux, they normally live until you explicitly kill them. A context manager hands that cleanup back to Python: you scope an object to a block, and libtmux kil...
- [Design decisions](https://libtmux.git-pull.com/topics/design-decisions/): This page explains the “why” behind libtmux’s shape: the four core choices it makes about representing tmux to your Python code. You don’t need any of it to get started — the defaults work out of t...
- [Filtering collections](https://libtmux.git-pull.com/topics/filtering/): Every collection libtmux hands you — server.sessions, session.windows, and window.panes — is a QueryList, a list that knows how to filter itself. You narrow one by calling filter() with keyword arg...
- [Floating panes](https://libtmux.git-pull.com/topics/floating_panes/): You can create floating panes — non-modal panes that hover above the tiled layout like a popup, but with full escape-sequence support and all the regular pane operations (capture, send-keys, and so...
- [Format-token fields](https://libtmux.git-pull.com/topics/format-tokens/): When you work with a libtmux object — Server, Session, Window, Pane, or Client — you get a flat set of typed string attributes that report the object’s current state straight from tmux, mirroring t...
- [Options and hooks](https://libtmux.git-pull.com/topics/options_and_hooks/): You shape how tmux sessions, windows, and panes behave by setting options — values like automatic-rename or the status-bar format — and by registering hooks, commands that tmux runs when an event f...
- [Pane interaction](https://libtmux.git-pull.com/topics/pane_interaction/): A Pane is a live terminal you drive from Python: you type into it, read back what it printed, resize it, and tear it down when you’re finished. That makes the pane the unit you reach for when autom...
- [Public vs internal API](https://libtmux.git-pull.com/topics/public-vs-internal/): You can import anything from the libtmux namespace and build on it: those names are the public API — documented, and changed only through a deprecation process announced ahead of time. (libtmux is ...
- [Locating yourself](https://libtmux.git-pull.com/topics/self_location/): Most libtmux code starts from a handle you already hold — you make a Server, you find a Session, you walk down. Sometimes you hold nothing, because your code is running inside a pane: a script you ...
- [Traversal](https://libtmux.git-pull.com/topics/traversal/): When you navigate a tmux server with libtmux, you move through a hierarchy of related objects: a Server holds Session objects, each session holds Window objects, and each window holds Pane objects....
- [Workspace setup](https://libtmux.git-pull.com/topics/workspace_setup/): A workspace is a single window carved into panes, each running its own program: an editor in one, a dev server in another, a log tail in a third. With libtmux you build that layout from Python inst...