tmuxp load

usage: tmuxp load [-h] [-L socket_name] [-S socket_path] [-f tmux_config_file]
                  [-s new_session_name] [--yes] [-d] [-a] [-2 | -8]
                  [--log-file file_path]
                  workspace-file [workspace-file ...]

Positional Arguments


filepath to session or filename of session in tmuxp workspace directory

Named Arguments


passthru to tmux(1) -L


passthru to tmux(1) -S


passthru to tmux(1) -f


start new session with new session name

--yes, -y

always answer yes

Default: False


load the session without attaching it

Default: False

-a, --append

load workspace, appending windows to the current session

Default: False


force tmux to assume the terminal supports 256 colours.


like -2, but indicates that the terminal supports 88 colours.


file to log errors/output to


You can load your tmuxp file and attach the vim session via a few shorthands:

  1. The directory with a .tmuxp.{yaml,yml,json} file in it

  2. The name of the project file in your $HOME/.tmuxp folder

  3. The direct path of the tmuxp file you want to load

Path to folder with .tmuxp.yaml, .tmuxp.yml, .tmuxp.json:

Projects with a file named .tmuxp.yaml or .tmuxp.json can be loaded:

// current directory
$ tmuxp load .
$ tmuxp load ../
$ tmuxp load path/to/folder/
$ tmuxp load /path/to/folder/

Name of the config, assume $HOME/.tmuxp/myconfig.yaml:

$ tmuxp load myconfig

Direct path to json/yaml file:

$ tmuxp load ./myfile.yaml
$ tmuxp load /abs/path/to/myfile.yaml
$ tmuxp load ~/myfile.yaml

Absolute and relative directory paths are supported.

$ tmuxp load [filename]

Inside sessions

If you try to load a workspace file from within a tmux session, it will ask you if you want to load and attach to the new session, or just load detached. You can also load a workspace file and append the windows to the current active session.

Already inside TMUX, switch to session? yes/no
Or (a)ppend windows in the current active session?


All of these options can be preselected to skip the prompt:

  • Attach / open client after load:

    $ tmuxp load -y config
  • Detached / open in background:

    $ tmuxp load -d config
  • Append windows to existing session

    $ tmuxp load -a config

Loading multiple sessions

Multiple sessions can be loaded at once. The first ones will be created without being attached. The last one will be attached if there is no -d flag on the command line.

$ tmuxp load [filename1] [filename2] ...

Custom session name

A session name can be provided at the terminal. If multiple sessions are created, the last session is named from the terminal.

$ tmuxp load -s [new_session_name] [filename1] ...


The output of the load command can be logged to a file for debugging purposes. the log level can be controlled with the global --log-level option (defaults to INFO).

$ tmuxp load [filename] --log-file [log_filename]
$ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]