# Environment

Source: https://libtmux.org/en/tmux/topics/environment/

> Locate tmux objects from process variables and manage the environment inherited by new panes.

tmux exposes two environment APIs. Process variables such as [`TMUX`](<https://libtmux.org/en/py/latest/reference/libtmux-_internal-env-tmux/>) and
[`TMUX_PANE`](<https://libtmux.org/en/py/latest/reference/libtmux-_internal-env-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](https://libtmux.org/en/tmux/topics/options-and-hooks/), this persistent store has explicit scopes.

## Locating yourself from inside a pane

Inside a pane, [`TMUX`](<https://libtmux.org/en/py/latest/reference/libtmux-_internal-env-tmux/>) contains `<socket path>,<server pid>,<session id>`, and
[`TMUX_PANE`](<https://libtmux.org/en/py/latest/reference/libtmux-_internal-env-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()`](<https://libtmux.org/en/py/latest/reference/libtmux-server-from_env/>)

**Session:** [`Session.from_env()`](<https://libtmux.org/en/py/latest/reference/libtmux-session-from_env/>)

**Window:** [`Window.from_env()`](<https://libtmux.org/en/py/latest/reference/libtmux-window-from_env/>)

**Pane:** [`Pane.from_env()`](<https://libtmux.org/en/py/latest/reference/libtmux-pane-from_env/>)

### TypeScript

**Server:** Not listed.

**Session:** [`Session.fromEnv()`](<https://libtmux.org/en/ts/latest/reference/session-session-fromenv/>)

**Window:** Not listed.

**Pane:** Not listed.

### Go

**Server:** [`NewServerFromEnv(env)`](<https://libtmux.org/en/go/latest/reference/tmux-newserverfromenv/>)

**Session:** [`SessionFromEnv(ctx, env)`](<https://libtmux.org/en/go/latest/reference/tmux-sessionfromenv/>)

**Window:** [`WindowFromEnv(ctx, env)`](<https://libtmux.org/en/go/latest/reference/tmux-windowfromenv/>)

**Pane:** [`PaneFromEnv(ctx, env)`](<https://libtmux.org/en/go/latest/reference/tmux-panefromenv/>)

### Rust

**Server:** [`Server::from_env()`](<https://libtmux.org/en/rs/latest/reference/server-server-from_env/>)

**Session:** [`Session::from_env(&server)`](<https://libtmux.org/en/rs/latest/reference/session-session-from_env/>)

**Window:** [`Window::from_env(&server)`](<https://libtmux.org/en/rs/latest/reference/window-window-from_env/>)

**Pane:** [`Pane::from_env(&server)`](<https://libtmux.org/en/rs/latest/reference/pane-pane-from_env/>)

### Java

**Server:** Not listed.

**Session:** Not listed.

**Window:** Not listed.

**Pane:** See the Java context example below.

### C#

**Server:** [`Server.FromEnvironment(env)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server-fromenvironment/>)

**Session:** [`Session.FromEnvironmentAsync()`](<https://libtmux.org/en/csharp/latest/reference/libtmux-session-fromenvironmentasync/>)

**Window:** [`Window.FromEnvironmentAsync()`](<https://libtmux.org/en/csharp/latest/reference/libtmux-window-fromenvironmentasync/>)

**Pane:** [`Pane.FromEnvironmentAsync()`](<https://libtmux.org/en/csharp/latest/reference/libtmux-pane-fromenvironmentasync/>)

### C++

**Server:** [`Server::from_env()`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-from_env/>)

**Session:** Not listed.

**Window:** Not listed.

**Pane:** Not listed.

### Swift

**Server:** [`TmuxContext.current()`](<https://libtmux.org/en/swift/latest/reference/tmuxcontext-current(environment-)/>)

**Session:** [`TmuxContext.current()`](<https://libtmux.org/en/swift/latest/reference/tmuxcontext-current(environment-)/>) (same call: see below)

**Window:** Not listed.

**Pane:** Not listed.

### Examples

[`Session`](<https://libtmux.org/en/rs/latest/reference/session-session/>), [`Window`](<https://libtmux.org/en/rs/latest/reference/window-window/>), and [`Pane::from_env`](<https://libtmux.org/en/rs/latest/reference/pane-pane-from_env/>) require an existing `&Server`.
Use [`Session.fromEnv()`](<https://libtmux.org/en/ts/latest/reference/session-session-fromenv/>) to resolve the session of the current process.

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

```typescript
const session = await Session.fromEnv();
```

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

```rust
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?;
```

```csharp
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`](<https://libtmux.org/en/py/latest/reference/libtmux-exc-notinsidetmux/>) reports a missing or invalid tmux environment.
Check the returned [`error`](<https://pkg.go.dev/builtin#error>). A [`FromEnvError`](<https://libtmux.org/en/go/latest/reference/tmux-fromenverror/>) identifies a missing or malformed
variable. Passing `nil` reads the process environment; pass an explicit map to
resolve a captured environment.
Handle [`TmuxObjectNotFoundException`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxobjectnotfoundexception/>) when the environment cannot identify an
object.

<a id="java-and-c-stop-short-of-the-pane"></a>

### Resolve the server socket

[`Server::from_env()`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-from_env/>) selects the socket. Use the resulting server to resolve
sessions or panes.

### Resolve context identifiers

[`TmuxEnvironment`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-tmuxenvironment-tmuxenvironment/>) parses `TMUX` and `TMUX_PANE` into identifiers: socket path, server
  PID, [`SessionId`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-sessionid-sessionid/>), and `Optional<PaneId>`. It returns context data rather than
  a live pane handle:

```java
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();
}
```

<a id="swift-reads-less-than-it-could"></a>

### Swift context fields

Swift's [`TmuxContext.current()`](<https://libtmux.org/en/swift/latest/reference/tmuxcontext-current(environment-)/>) parses the socket path, server PID, and session
ID from `TMUX`. It does not read `TMUX_PANE`, so it cannot identify the current
pane:

```swift
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`](<https://libtmux.org/en/swift/latest/reference/tmuxcontext/>) does not
provide it.

## tmux's own environment variable store

Like [Options and hooks](https://libtmux.org/en/tmux/topics/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)`](<https://libtmux.org/en/py/latest/reference/libtmux-server-set_environment/>), [`session.set_environment(...)`](<https://libtmux.org/en/py/latest/reference/libtmux-session-set_environment/>)

**Read all:** [`server.show_environment()`](<https://libtmux.org/en/py/latest/reference/libtmux-server-show_environment/>), [`session.show_environment()`](<https://libtmux.org/en/py/latest/reference/libtmux-session-show_environment/>)

**Unset:** [`server.unset_environment(name)`](<https://libtmux.org/en/py/latest/reference/libtmux-server-unset_environment/>). See below for `.remove_environment()`.

### TypeScript

**Set:** [`server.setEnvironment(name, value)`](<https://libtmux.org/en/ts/latest/reference/server-server-setenvironment/>), [`session.setEnvironment(...)`](<https://libtmux.org/en/ts/latest/reference/session-session-setenvironment/>)

**Read all:** [`server.showEnvironment()`](<https://libtmux.org/en/ts/latest/reference/server-server-showenvironment/>), [`session.showEnvironment()`](<https://libtmux.org/en/ts/latest/reference/session-session-showenvironment/>)

**Unset:** [`server.unsetEnvironment(name)`](<https://libtmux.org/en/ts/latest/reference/server-server-unsetenvironment/>), [`session.unsetEnvironment(name)`](<https://libtmux.org/en/ts/latest/reference/session-session-unsetenvironment/>)

### Go

**Set:** [`server.SetEnvironment(ctx, name, value, opts)`](<https://libtmux.org/en/go/latest/reference/tmux-server-setenvironment/>) (global, `-g`)

**Read all:** [`server.ShowEnvironment(ctx)`](<https://libtmux.org/en/go/latest/reference/tmux-server-showenvironment/>)

**Unset:** [`server.UnsetEnvironment(ctx, name)`](<https://libtmux.org/en/go/latest/reference/tmux-server-unsetenvironment/>)

### Rust

**Set:** [`server.set_environment(...)`](<https://libtmux.org/en/rs/latest/reference/server-server-set_environment/>), [`session.set_environment(...)`](<https://libtmux.org/en/rs/latest/reference/session-session-set_environment/>)

**Read all:** [`server.environment_all()`](<https://libtmux.org/en/rs/latest/reference/server-server-environment_all/>), [`session.environment_all()`](<https://libtmux.org/en/rs/latest/reference/session-session-environment_all/>)

**Unset:** [`server.unset_environment(name)`](<https://libtmux.org/en/rs/latest/reference/server-server-unset_environment/>), [`session.unset_environment(name)`](<https://libtmux.org/en/rs/latest/reference/session-session-unset_environment/>)

### 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)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-setasync/>),
[`session.Environment.SetAsync(...)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-setasync/>)

**Read all:** [`server.Environment.GetAllAsync()`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-getallasync/>)

**Unset:** [`server.Environment.UnsetAsync(name)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-unsetasync/>), [`.RemoveAsync(name)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-removeasync/>)

### 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)`](<https://libtmux.org/en/swift/latest/reference/server-setenvironment(_-to-in-)/>)

**Read all:** [`server.environment(scope)`](<https://libtmux.org/en/swift/latest/reference/server-environment(_-)/>)

**Unset:** [`server.unsetEnvironment(name, in: scope)`](<https://libtmux.org/en/swift/latest/reference/server-unsetenvironment(_-in-)/>), [`.removeEnvironment(name,
in:)`](<https://libtmux.org/en/swift/latest/reference/server-removeenvironment(_-in-)/>)

### Examples

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

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

```go
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)
```

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

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

```swift
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`](<https://libtmux.org/en/swift/latest/reference/server-unsetenvironment(_-in-)/>) for `-u`, or [`removeEnvironment`](<https://libtmux.org/en/swift/latest/reference/server-removeenvironment(_-in-)/>) for `-r`.
Use `.UnsetAsync` for `-u`, or [`.RemoveAsync`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxenvironment-removeasync/>) for `-r`.

<a id="java-and-c-no-verified-access-to-this-table-at-all"></a>

### Process environment

[`SessionSpec.Builder.environment(Map)`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-sessionspec-sessionspec-builder-environment/>), [`WindowSpec.Builder.environment(Map)`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-windowspec-windowspec-builder-environment/>),
and [`SplitSpec.Builder.environment(Map)`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-splitspec-splitspec-builder-environment/>) 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.