Skip to content

Latest commit

 

History

History
207 lines (132 loc) · 4.5 KB

quickstart.md

File metadata and controls

207 lines (132 loc) · 4.5 KB

(quickstart)=

Quickstart

Installation

Ensure you have at least tmux >= 3.2 and python >= 3.9.

$ pip install --user tmuxp

If you're managing dependencies with uv_ inside a project environment, add tmuxp directly to your lockfile:

$ uv add tmuxp

To run tmuxp without installing it globally—similar to what you'd do with pipx—invoke it via uvx_:

$ uvx tmuxp

You can upgrade to the latest release with:

$ pip install --user --upgrade tmuxp

Within a uv-managed project you can upgrade by refreshing the lockfile and syncing the environment:

$ uv lock --upgrade-package tmuxp
$ uv sync

Then install {ref}completion.

If you are a Homebrew user you can install it with:

$ brew install tmuxp

(developmental-releases)=

Developmental releases

New versions of tmuxp are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like a1, b1, and rc1, respectively. 1.10.0b4 would mean the 4th beta release of 1.10.0 before general availability.

  • pip:

    $ pip install --user --upgrade --pre tmuxp

  • uv_:

    $ uv add tmuxp --prerelease allow

  • uvx_:

    $ uvx --from 'tmuxp' --prerelease allow tmuxp

  • pipx:

    $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force

    Then use tmuxp@next load [session].

via trunk (can break easily):

  • pip:

    $ pip install --user -e git+https://github.com/tmux-python/tmuxp.git#egg=tmuxp

  • uv_:

    $ uv add "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master"

  • uvx_:

    $ uvx --from "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master" tmuxp

  • pipx:

    $ pipx install --suffix=@master 'tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master' --force

Commands

:::{seealso}

{ref}examples, {ref}commands, {ref}completion.

:::

tmuxp launches workspaces / sessions from JSON and YAML files.

Workspace files can be stored in $HOME/.tmuxp or in project directories as .tmuxp.py, .tmuxp.json or .tmuxp.yaml.

Every workspace file is required to have:

  1. session_name
  2. list of windows
  3. list of panes for every window in windows

Create a file, ~/.tmuxp/example.yaml:

:language: yaml


$ tmuxp load example.yaml

This creates your tmuxp session.

Load multiple tmux sessions at once:

$ tmuxp load example.yaml anothersession.yaml

tmuxp will offer to switch-client for you if you're already in a session. You can also load a workspace and append the windows to the current active session.

You can also have a custom tmuxp config directory by setting the TMUXP_CONFIGDIR in your environment variables.

$ TMUXP_CONFIGDIR=$HOME/.tmuxpmoo tmuxp load cpython

Or in your ~/.bashrc / ~/.zshrc you can set:

export TMUXP_CONFIGDIR=$HOME/.yourconfigdir/tmuxp

You can also Import configs teamocil and tmuxinator.

Pythonics

:::{seealso}

{ref}libtmux python API documentation <libtmux:api> and {ref}developing.

:::

ORM - Object Relational Mapper

AL - Abstraction Layer

python abstraction layer

{ref}tmuxp python api <libtmux:api> {term}tmux(1) equivalent
{meth}libtmux.Server.new_session $ tmux new-session
{meth}libtmux.Server.sessions $ tmux list-sessions
{meth}libtmux.Session.windows $ tmux list-windows
{meth}libtmux.Session.new_window $ tmux new-window
{meth}libtmux.Window.panes $ tmux list-panes
{meth}libtmux.Window.split $ tmux split-window
{meth}libtmux.Pane.send_keys $ tmux send-keys