Environment

tmux exposes two environment APIs. Process variables such as kTMUX and kTMUX_PANE let code inside a pane identify its server and pane. The server also stores variables through $set-environment and $show-environment for new processes to inherit. Like the tables in Options and hooks, this persistent store has explicit scopes.

Locating yourself from inside a pane¶

Inside a pane, kTMUX contains <socket path>,<server pid>,<session id>, and kTMUX_PANE contains the pane ID, such as %1. Use these variables to locate the current tmux objects. Select the object your operation needs:

Server: mServer.from_env()

Session: mSession.from_env()

Window: mWindow.from_env()

Pane: mPane.from_env()

Examples¶

Pane.from_env().pane_id
Window.from_env().window_id
Session.from_env().session_id
Server.from_env().sessions

Environment lookup requires valid tmux targeting variables. If your process can run outside tmux, handle that case before using the result.

!NotInsideTmux reports a missing or invalid tmux environment.

tmux’s own environment variable store¶

Like Options and hooks, tmux’s persistent environment store has global and per-session scopes. It is read with $show-environment and updated with $set-environment. Newly spawned processes inherit it; existing processes retain their own environments.

Set: mserver.set_environment(name, value), msession.set_environment(...)

Read all: mserver.show_environment(), msession.show_environment()

Unset: mserver.unset_environment(name). See below for .remove_environment().

Examples¶

server.set_environment("EDITOR", "vim")     # global
session.set_environment("EDITOR", "hx")     # this session only
session.show_environment()

$set-environment writes a value. Its -u flag removes the entry, while -r marks the variable for exclusion from new processes, including values tmux inherited at startup. The listing retains an excluded variable as -NAME.

Use unset_environment for -u, or remove_environment for -r.