# tmux attach-session

Source: https://libtmux.org/en/tmux/3.7c/manual/attach-session/

> If run from outside tmux, attach to target-session in the current terminal.

If run from outside tmux, attach to target-session in the current terminal.

## Syntax

```tmux-usage
tmux attach-session [-dErx] [-c working-directory] [-f flags] [-t target-session]
```

Alias: `attach`.

## Behavior

If run from outside `tmux`, attach to `target-session` in the current terminal. `target-session` must already exist - to create a new session, see the [`new-session`](https://libtmux.org/en/tmux/3.7c/manual/new-session/) command (with `-A` to create or attach). If used from inside, switch the currently attached session to `target-session`. If `-d` is specified, any other clients attached to the session are detached. If `-x` is given, send `SIGHUP` to the parent process of the client as well as detaching the client, typically causing it to exit. `-f` sets a comma-separated list of client flags. The flags are:

* [active-pane](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-active-pane)

  the client has an independent active pane

* [ignore-size](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-ignore-size)

  the client does not affect the size of other clients

* [no-detach-on-destroy](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-no-detach-on-destroy)

  do not detach the client when the session it is attached to is destroyed if there are any other sessions

* [no-output](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-no-output)

  the client does not receive pane output in control mode

* [pause-after=seconds](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-pause-after-seconds)

  output is paused once the pane is `seconds` behind in control mode

* [read-only](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-read-only)

  the client is read-only

* [wait-exit](https://libtmux.org/en/tmux/3.7c/manual/attach-session/#attach-session-wait-exit)

  wait for an empty line input before exiting in control mode

A leading ‘`!`’ turns a flag off if the client is already attached. `-r` is an alias for `-f` `read-only,ignore-size`. When a client is read-only, only keys bound to the [`detach-client`](https://libtmux.org/en/tmux/3.7c/manual/detach-client/) or [`switch-client`](https://libtmux.org/en/tmux/3.7c/manual/switch-client/) commands have any effect. A client with the `active-pane` flag allows the active pane to be selected independently of the window's active pane used by clients without the flag. This only affects the cursor position and commands issued from the client; other features such as hooks and styles continue to use the window's active pane.

If no server is started, [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/) will attempt to start it; this will fail unless sessions are created in the configuration file.

The `target-session` rules for [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/) are slightly adjusted: if `tmux` needs to select the most recently used session, it will prefer the most recently used [*unattached*](https://libtmux.org/en/tmux/3.7c/manual/full/#unattached) session.

`-c` will set the session working directory (used for new windows) to `working-directory`.

If `-E` is used, the `update-environment` option will not be applied.

## Guides

* [Attach to an existing session](https://libtmux.org/en/tmux/guides/attaching-to-tmux/)

## C implementation

Internal declarations in tmux 3.7c:

* [`cmd_attach_session_entry`](https://libtmux.org/en/tmux/3.7c/reference/c-variable-cmd_attach_session_entry/)
* [`cmd_attach_session_exec`](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd-attach-session-c-cmd_attach_session_exec/)

## Use from a library

Each API describes its own defaults, errors and execution model.

* [Python](https://libtmux.org/en/py/latest/reference/libtmux-session-attach/)
* [Rust](https://libtmux.org/en/rs/latest/reference/control-controlmode-attach/)
* [Go](https://libtmux.org/en/go/latest/reference/tmux-server-attachsession/)
* [Java](https://libtmux.org/en/java/latest/reference/io-github-libtmux-control-controlclient-controlclient-attach/)
* [C#](https://libtmux.org/en/csharp/latest/reference/libtmux-server-attachsessionasync/)
* [C++](https://libtmux.org/en/cxx/latest/reference/libtmux-session-attach_command/)

tmux sources and license

Syntax comes from `tmux 3.7c list-commands`. See the [global options](https://libtmux.org/en/tmux/3.7c/manual/full/#DESCRIPTION) for sockets and configuration, and [command syntax and targets](https://libtmux.org/en/tmux/3.7c/manual/full/#COMMANDS).

Behavior is taken from the [tmux 3.7c manual](https://github.com/tmux/tmux/blob/79072dd1a9f5fb437a5859e362a496fd57ec0981/tmux.1).

[Command declaration](https://github.com/tmux/tmux/blob/79072dd1a9f5fb437a5859e362a496fd57ec0981/cmd-attach-session.c#L37)

```
Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com>

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER
IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
```