---
title: "Sessions - Wez's Terminal Emulator"
source: "https://wezterm.org/recipes/workspaces.html"
author:
published:
created: 2026-04-17
description: "Wez's Terminal Emulator"
tags:
  - "clippings"
---
## Workspaces / Sessions

If you are familiar with tmux then you may have used its session functionality to manage separate groups of related tmux windows (which map to tabs in wezterm).

wezterm doesn't have an exact match to tmux sessions, but does have a similar concept known as *Workspaces*.

Every [MuxWindow](https://wezterm.org/config/lua/mux-window/index.html) is associated with a workspace, which is just a label.

The wezterm GUI is focused on the active workspace, which means that it will present a GUI window for each MuxWindow that is present in that workspace.

You can spawn windows into differently named workspaces and they won't become visible until you set the active workspace to that name.

When switching the active workspace, wezterm will swap the contents of the GUI windows with the MuxWindows that belong to the now-focused workspace.

The following key assignments are helpful when working with workspaces:

- [SwitchToWorkspace](https://wezterm.org/config/lua/keyassignment/SwitchToWorkspace.html)
- [SwitchWorkspaceRelative](https://wezterm.org/config/lua/keyassignment/SwitchWorkspaceRelative.html)
- Various key assignments or functions that spawn windows also allow specifying the workspace name to be used
- [ShowLauncher](https://wezterm.org/config/lua/keyassignment/ShowLauncher.html) and [ShowLauncherArgs](https://wezterm.org/config/lua/keyassignment/ShowLauncherArgs.html) will list the current set of workspaces and allow switching between them

You can pre-define a layout of windows/tabs/panes in specific workspaces by using these events:

- [gui-startup](https://wezterm.org/config/lua/gui-events/gui-startup.html)
- [mux-startup](https://wezterm.org/config/lua/mux-events/mux-startup.html)