# tmuxp > Session manager for tmux. Load, freeze, and convert tmux sessions through YAML/JSON configuration files. Powered by libtmux. ## Documentation - [Quickstart](https://tmuxp.git-pull.com/quickstart/): Ensure you have at least tmux >= 3.2 and python >= 3.9. - [CLI Reference](https://tmuxp.git-pull.com/cli/): Load tmux sessions from workspace configs. - [Workspace files](https://tmuxp.git-pull.com/configuration/): Session and window configuration keys. - [Topics](https://tmuxp.git-pull.com/topics/): Conceptual guides and workflow documentation. - [Internals](https://tmuxp.git-pull.com/internals/): How the CLI dispatches to the workspace builder and libtmux. - [Project](https://tmuxp.git-pull.com/project/): Information for contributors and maintainers. - [Changelog](https://tmuxp.git-pull.com/history/): To install the unreleased tmuxp version, see developmental-releases. ## More - [The Tao of tmux](https://tmuxp.git-pull.com/about_tmux/): tmux is geared for developers and admins who interact regularly with CLI (text-only interfaces) - [Migration notes](https://tmuxp.git-pull.com/migration/): Migration and deprecation notes for tmuxp are here, see changelog as well. - [Glossary](https://tmuxp.git-pull.com/glossary/): A tool to manage workspaces with tmux. A pythonic abstraction of tmux. ## Documentation - [Completions](https://tmuxp.git-pull.com/cli/completion/): Provisional support for completions in tmuxp 1.17+ are powered by shtab. This must be installed separately, as it’s not currently bundled with tmuxp. - [tmuxp convert](https://tmuxp.git-pull.com/cli/convert/): Convert workspace configuration files between YAML and JSON formats. - [tmuxp debug-info](https://tmuxp.git-pull.com/cli/debug-info/): Collect and display system information useful for debugging tmuxp issues and submitting bug reports. - [tmuxp edit](https://tmuxp.git-pull.com/cli/edit/): Open a workspace configuration file in your default editor for quick modifications. - [Exit Codes](https://tmuxp.git-pull.com/cli/exit-codes/): tmuxp uses standard exit codes for scripting and automation. - [tmuxp freeze](https://tmuxp.git-pull.com/cli/freeze/): Export a running tmux session to a workspace configuration file. This allows you to save the current state of your tmux session for later restoration. - [tmuxp import](https://tmuxp.git-pull.com/cli/import/): Import and convert workspace configurations from other tmux session managers like teamocil and tmuxinator. - [tmuxp load](https://tmuxp.git-pull.com/cli/load/): Load tmux sessions from workspace configuration files. This is the primary command for starting sessions from YAML or JSON configurations. - [tmuxp ls](https://tmuxp.git-pull.com/cli/ls/): List available workspace configurations from your local project and global tmuxp directories. - [Recipes](https://tmuxp.git-pull.com/cli/recipes/): Copy-pasteable command invocations for common tasks. - [tmuxp search](https://tmuxp.git-pull.com/cli/search/): Search for workspace configurations by name or content across your tmuxp directories. - [tmuxp shell](https://tmuxp.git-pull.com/cli/shell/): Launch an interactive Python shell with libtmux objects pre-loaded. Similar to Django’s shell command, this provides quick access to your tmux server, sessions, windows, and panes for scripting and... - [Environmental variables](https://tmuxp.git-pull.com/configuration/environmental-variables/): Example: TMUXP_CONFIGDIR=$HOME/.mytmuxpconfigdir tmuxp load cpython - [Examples](https://tmuxp.git-pull.com/configuration/examples/): tmuxp has a short-hand syntax for those who wish to keep their workspace punctual. - [Top-level configuration](https://tmuxp.git-pull.com/configuration/top-level/): Used for: - [Colors - tmuxp._internal.colors](https://tmuxp.git-pull.com/internals/api/_internal/colors/): Color output utilities for tmuxp CLI. - [Config reader - tmuxp._internal.config_reader](https://tmuxp.git-pull.com/internals/api/_internal/config_reader/): Configuration parser for YAML and JSON files. - [Internal Modules](https://tmuxp.git-pull.com/internals/api/_internal/) - [Private path - tmuxp._internal.private_path](https://tmuxp.git-pull.com/internals/api/_internal/private_path/): Privacy-aware path utilities for hiding sensitive directory information. - [Typings - tmuxp._internal.types](https://tmuxp.git-pull.com/internals/api/_internal/types/): Internal, typing.TYPE_CHECKING guarded typings. - [tmuxp convert - tmuxp.cli.convert](https://tmuxp.git-pull.com/internals/api/cli/convert/): CLI for tmuxp convert subcommand. - [tmuxp debug-info - tmuxp.cli.debug_info](https://tmuxp.git-pull.com/internals/api/cli/debug_info/): CLI for tmuxp debug-info subcommand. - [tmuxp edit - tmuxp.cli.edit](https://tmuxp.git-pull.com/internals/api/cli/edit/): CLI for tmuxp edit subcommand. - [tmuxp freeze - tmuxp.cli.freeze](https://tmuxp.git-pull.com/internals/api/cli/freeze/): CLI for tmuxp freeze subcommand. - [tmuxp import - tmuxp.cli.import_config](https://tmuxp.git-pull.com/internals/api/cli/import_config/): CLI for tmuxp import subcommand. - [CLI](https://tmuxp.git-pull.com/internals/api/cli/): CLI utilities for tmuxp. - [tmuxp load - tmuxp.cli.load](https://tmuxp.git-pull.com/internals/api/cli/load/): CLI for tmuxp load subcommand. - [tmuxp ls - tmuxp.cli.ls](https://tmuxp.git-pull.com/internals/api/cli/ls/): CLI for tmuxp ls subcommand. - [tmuxp progress - tmuxp.cli._progress](https://tmuxp.git-pull.com/internals/api/cli/progress/): Progress indicators for tmuxp CLI. - [tmuxp search - tmuxp.cli.search](https://tmuxp.git-pull.com/internals/api/cli/search/): CLI for tmuxp search subcommand. - [tmuxp shell - tmuxp.cli.shell](https://tmuxp.git-pull.com/internals/api/cli/shell/): CLI for tmuxp shell subcommand. - [CLI utilities - tmuxp.cli.utils](https://tmuxp.git-pull.com/internals/api/cli/utils/): CLI utility helpers for tmuxp. - [Exceptions - tmuxp.exc](https://tmuxp.git-pull.com/internals/api/exc/): Exceptions for tmuxp. - [API Reference](https://tmuxp.git-pull.com/internals/api/) - [Logging - tmuxp.log](https://tmuxp.git-pull.com/internals/api/log/): Log utilities for tmuxp. - [Plugin - tmuxp.plugin](https://tmuxp.git-pull.com/internals/api/plugin/): Plugin system for tmuxp. - [Shell - tmuxp.shell](https://tmuxp.git-pull.com/internals/api/shell/): Utility and helper methods for tmuxp. - [Typings - tmuxp.types](https://tmuxp.git-pull.com/internals/api/types/): Internal type annotations. - [Utilities - tmuxp.util](https://tmuxp.git-pull.com/internals/api/util/): Utility and helper methods for tmuxp. - [Builder - tmuxp.workspace.builder](https://tmuxp.git-pull.com/internals/api/workspace/builder/): Create a tmux workspace from a workspace dict. - [Constants - tmuxp.workspace.constants](https://tmuxp.git-pull.com/internals/api/workspace/constants/): Constant variables for tmuxp workspace functionality. - [Finders - tmuxp.workspace.finders](https://tmuxp.git-pull.com/internals/api/workspace/finders/): Workspace (configuration file) finders for tmuxp. - [Freezer - tmuxp.workspace.freezer](https://tmuxp.git-pull.com/internals/api/workspace/freezer/): Tmux session freezing functionality for tmuxp. - [Importers - tmuxp.workspace.importers](https://tmuxp.git-pull.com/internals/api/workspace/importers/): Configuration import adapters to load teamocil, tmuxinator, etc. in tmuxp. - [Workspace](https://tmuxp.git-pull.com/internals/api/workspace/) - [Loader - tmuxp.workspace.loader](https://tmuxp.git-pull.com/internals/api/workspace/loader/): Workspace hydration and loading for tmuxp. - [Validation - tmuxp.workspace.validation](https://tmuxp.git-pull.com/internals/api/workspace/validation/): Validation errors for tmuxp configuration files. - [Architecture](https://tmuxp.git-pull.com/internals/architecture/): How the tmuxp CLI dispatches commands to the underlying library. - [Code Style](https://tmuxp.git-pull.com/project/code-style/): tmuxp uses ruff for both linting and formatting. - [Developing and Testing](https://tmuxp.git-pull.com/project/contributing/): Our tests are inside tests/. Tests are implemented using pytest. - [Releasing](https://tmuxp.git-pull.com/project/releasing/): Releases are triggered by git tags and published to PyPI via OIDC trusted publishing. - [Library vs CLI](https://tmuxp.git-pull.com/topics/library-vs-cli/): tmuxp is a CLI tool. libtmux is the Python library it’s built on. Both control tmux, but they serve different needs. - [Plugins](https://tmuxp.git-pull.com/topics/plugins/): The plugin system allows users to customize and extend different aspects of tmuxp without the need to change tmuxp itself. - [Troubleshooting](https://tmuxp.git-pull.com/topics/troubleshooting/): Ensure tmuxp is installed and on your PATH: - [Workflows](https://tmuxp.git-pull.com/topics/workflows/): tmuxp can set up tmux sessions in CI pipelines for integration testing: