Environment

tmux exposes two environment APIs. Process variables such as TMUX and TMUX_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, TMUX contains <socket path>,<server pid>,<session id>, and TMUX_PANE contains the pane ID, such as %1. Use these variables to locate the current tmux objects. Select the object your operation needs:

Python¶

Server: Server.from_env()

Session: Session.from_env()

Window: Window.from_env()

Pane: Pane.from_env()

TypeScript¶

Server: Not listed.

Session: Session.fromEnv()

Window: Not listed.

Pane: Not listed.

Go¶

Server: NewServerFromEnv(env)

Session: SessionFromEnv(ctx, env)

Window: WindowFromEnv(ctx, env)

Pane: PaneFromEnv(ctx, env)

Rust¶

Server: Server::from_env()

Session: Session::from_env(&server)

Window: Window::from_env(&server)

Pane: Pane::from_env(&server)

Java¶

Server: Not listed.

Session: Not listed.

Window: Not listed.

Pane: See the Java context example below.

C#¶

Server: Server.FromEnvironment(env)

Session: Session.FromEnvironmentAsync()

Window: Window.FromEnvironmentAsync()

Pane: Pane.FromEnvironmentAsync()

C++¶

Server: Server::from_env()

Session: Not listed.

Window: Not listed.

Pane: Not listed.

Swift¶

Server: TmuxContext.current()

Session: TmuxContext.current() (same call: see below)

Window: Not listed.

Pane: Not listed.

Examples¶

Session, Window, and Pane::from_env require an existing &Server. Use Session.fromEnv() to resolve the session of the current process.

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

const session = await Session.fromEnv();

pane, err := tmux.PaneFromEnv(ctx, nil)
if err != nil {
    return err
}
fmt.Println("current pane:", pane.ID())

let server = libtmux::Server::from_env()?;
let session = libtmux::Session::from_env(&server).await?; // Option<Session>
let window = libtmux::Window::from_env(&server).await?;
let pane = libtmux::Pane::from_env(&server).await?;

Server server = Server.FromEnvironment(null);
Session session = await Session.FromEnvironmentAsync();
Window window = await Window.FromEnvironmentAsync();
Pane pane = await Pane.FromEnvironmentAsync();

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. Check the returned error. A FromEnvError identifies a missing or malformed variable. Passing nil reads the process environment; pass an explicit map to resolve a captured environment. Handle TmuxObjectNotFoundException when the environment cannot identify an object.

Resolve the server socket¶

Server::from_env() selects the socket. Use the resulting server to resolve sessions or panes.

Resolve context identifiers¶

TmuxEnvironment parses TMUX and TMUX_PANE into identifiers: socket path, server PID, SessionId, and Optional<PaneId>. It returns context data rather than a live pane handle:

TmuxEnvironment here = TmuxEnvironment.current().orElseThrow();

try (Server server = Server.open(here.config())) {
    Session mine = server.sessions().stream()
          .filter(session -> session.id().equals(here.session()))
          .findFirst()
          .orElseThrow();
}

Swift context fields¶

Swift's TmuxContext.current() parses the socket path, server PID, and session ID from TMUX. It does not read TMUX_PANE, so it cannot identify the current pane:

let context = TmuxContext.current()! // socket path, server pid, session id
let server = try context.server()

Read TMUX_PANE separately if you need the pane ID; TmuxContext does not provide it.

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.

Python¶

Set: server.set_environment(name, value), session.set_environment(...)

Read all: server.show_environment(), session.show_environment()

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

TypeScript¶

Set: server.setEnvironment(name, value), session.setEnvironment(...)

Read all: server.showEnvironment(), session.showEnvironment()

Unset: server.unsetEnvironment(name), session.unsetEnvironment(name)

Go¶

Set: server.SetEnvironment(ctx, name, value, opts) (global, -g)

Read all: server.ShowEnvironment(ctx)

Unset: server.UnsetEnvironment(ctx, name)

Rust¶

Set: server.set_environment(...), session.set_environment(...)

Read all: server.environment_all(), session.environment_all()

Unset: server.unset_environment(name), session.unset_environment(name)

Java¶

Set: Not documented here; see the process-environment note below.

Read all: Not documented here; see the process-environment note below.

Unset: Not documented here; see the process-environment note below.

C#¶

Set: server.Environment.SetAsync(name, value), session.Environment.SetAsync(...)

Read all: server.Environment.GetAllAsync()

Unset: server.Environment.UnsetAsync(name), .RemoveAsync(name)

C++¶

Set: Not documented here; see the process-environment note below.

Read all: Not documented here; see the process-environment note below.

Unset: Not documented here; see the process-environment note below.

Swift¶

Set: server.setEnvironment(name, to: value, in: scope)

Read all: server.environment(scope)

Unset: server.unsetEnvironment(name, in: scope), .removeEnvironment(name, in:)

Examples¶

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

await server.setEnvironment("EDITOR", "vim");
await session.setEnvironment("EDITOR", "hx");
await session.showEnvironment();

if err := session.SetEnvironment(ctx, "EDITOR", "hx", tmux.SetEnvironmentOptions{}); err != nil {
    return err
}
values, err := session.ShowEnvironment(ctx)
if err != nil {
    return err
}
fmt.Println(values)

server.set_environment("EDITOR", "vim").await?;
session.set_environment("EDITOR", "hx").await?;
session.environment_all().await?;

await server.Environment.SetAsync("EDITOR", "vim");
await session.Environment.SetAsync("EDITOR", "hx");
await session.Environment.GetAllAsync();

try await server.setEnvironment("EDITOR", to: "vim", in: .global)
try await server.setEnvironment("EDITOR", to: "hx", in: .session(session.id.rawValue))
try await server.environment(.session(session.id.rawValue))

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. Use unsetEnvironment for -u, or removeEnvironment for -r. Use .UnsetAsync for -u, or .RemoveAsync for -r.

Process environment¶

SessionSpec.Builder.environment(Map), WindowSpec.Builder.environment(Map), and SplitSpec.Builder.environment(Map) pass initial variables to new-session -e, new-window -e, and split-window -e. These creation options do not change the stored environment of an existing session.

Process environment¶

Creation-time environment values affect the new process. They do not update an existing process's environment. To change tmux's persistent table, use set-environment on the same socket as the server handle.