# tmuxp.cli.load.load_workspace

- **Module:** tmuxp.cli.load
- **Package:** tmuxp
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/tmuxp/blob/153acdf6ff1268b14d3d03ed488f545a7123c8f1/src/tmuxp/cli/load.py#L459
- **Page:** https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-load_workspace/

```
tmuxp.cli.load.load_workspace(
    workspace_file: StrPath,
    socket_name: str | None = None,
    socket_path: str | None = None,
    tmux_config_file: str | None = None,
    new_session_name: str | None = None,
    colors: int | None = None,
    detached: bool = False,
    answer_yes: bool = False,
    append: bool = False,
    cli_colors: Colors | None = None,
    progress_format: str | None = None,
    panel_lines: int | None = None,
    no_progress: bool = False,
) -> Session | None
```

Entrypoint for ``tmuxp load``, load a tmuxp "workspace" session via config file.

### Notes

tmuxp will check and load a workspace file. The file will use
:class:`~tmuxp._internal.config_reader.ConfigReader` to load a JSON/YAML
into a :class:`dict`. Then :func:`~tmuxp.workspace.loader.expand` and
:func:`~tmuxp.workspace.loader.trickle` will be used to expand any
shorthands, template variables, or file paths relative to where the
config/script is executed from.

:func:`~tmuxp.workspace.loader.expand` accepts the directory of the config
file, so the user's workspace can resolve absolute paths relative to where
the workspace file is. In otherwords, if a workspace file at
*/var/moo/hi.yaml* has *./* in its workspaces, we want to be sure any file
path with *./* is relative to */var/moo*, not the user's PWD.

A :class:`libtmux.Server` object is created. No tmux server is started yet,
just the object.

The prepared workspace and its server object is passed into an instance
of :class:`~tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol`.

A sanity check against :meth:`libtmux.common.which` is ran. It will raise
an exception if tmux isn't found.

If a tmux session under the same name as [`session_name`](/en/tmux/latest/catalog/formats/session_name/) in the tmuxp
workspace exists, tmuxp offers to attach the session. Currently, tmuxp
does not allow appending a workspace / incremental building on top of a
current session (pull requests are welcome!).

:meth:`~tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol.build`
will build the session in the background via using tmux's detached state
(``-d``).

After the session (workspace) is built, unless the user decided to load
the session in the background via ``tmuxp -d`` (which is in the spirit
of tmux's ``-d``), we need to prompt the user to attach the session.

If the user is already inside a tmux client, which we detect via the
``TMUX`` environment variable bring present, we will prompt the user to
switch their current client to it.

If they're outside of tmux client - in a plain-old PTY - we will
automatically ``attach``.

If an exception is raised during the building of the workspace, tmuxp will
prompt to cleanup ([`$ tmux kill-session`](/en/tmux/latest/manual/kill-session/)) the session on the user's
behalf. An exception raised during this process means it's not easy to
predict how broken the session is.

## Parameters

- `workspace_file` (`StrPath`): paths or session names to workspace files
- `socket_name` (`str | None`): ``tmux -L <socket-name>``
- `socket_path` (`str | None`): ``tmux -S <socket-path>``
- `tmux_config_file` (`str | None`)
- `new_session_name` (`str | None`): ``tmux new -s <new_session_name>``
- `colors` (`int | None`): Force tmux to support 256 or 88 colors.
- `detached` (`bool`): Force detached state. default False.
- `answer_yes` (`bool`): Assume yes when given prompt to attach in new session.
Default False.
- `append` (`bool`): Assume current when given prompt to append windows in same session.
Default False.
- `cli_colors` (`Colors | None`): Colors instance for CLI output formatting. If None, uses
:attr:`~tmuxp._internal.colors.ColorMode.AUTO`.
- `progress_format` (`str | None`): Spinner format preset name or custom format string with tokens.
- `panel_lines` (`int | None`): Number of script-output lines shown in the spinner panel.
Defaults to the :class:`~tmuxp.cli._progress.Spinner` default (3).
Override via ``TMUXP_PROGRESS_LINES`` environment variable.
- `no_progress` (`bool`): Disable the progress spinner entirely. Default False.
Also disabled when ``TMUXP_PROGRESS=0``.