# tmux new-session

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

> Create a new session with name session-name.

Create a new session with name session-name.

## Syntax

```tmux-usage
tmux new-session [-AdDEPX] [-c start-directory] [-e environment] [-F format] [-f flags] [-n window-name] [-s session-name] [-t target-session] [-x width] [-y height] [shell-command [argument ...]]
```

Alias: `new`.

## Behavior

Create a new session with name `session-name`.

The new session is attached to the current terminal unless `-d` is given. `window-name` and `shell-command` are the name of and shell command to execute in the initial window. With `-d`, the initial size comes from the global `default-size` option; `-x` and `-y` can be used to specify a different size. ‘`-`’ uses the size of the current client if any. If `-x` or `-y` is given, the `default-size` option is set for the session. `-f` sets a comma-separated list of client flags (see [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/)).

If run from a terminal, any [termios(4)]() special characters are saved and used for new windows in the new session.

The `-A` flag makes [`new-session`](https://libtmux.org/en/tmux/3.7c/manual/new-session/) behave like [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/) if `session-name` already exists; if `-A` is given, `-D` behaves like `-d` to [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/), and `-X` behaves like `-x` to [`attach-session`](https://libtmux.org/en/tmux/3.7c/manual/attach-session/).

If `-t` is given, it specifies a `session group`. Sessions in the same group share the same set of windows - new windows are linked to all sessions in the group and any windows closed removed from all sessions. The current and previous window and any session options remain independent and any session in a group may be killed without affecting the others. The `group-name` argument may be:

1. the name of an existing group, in which case the new session is added to that group;
2. the name of an existing session - the new session is added to the same group as that session, creating a new group if necessary;
3. the name for a new group containing only the new session.

`-n` and `shell-command` are invalid if `-t` is used.

The `-P` option prints information about the new session after it has been created. By default, it uses the format ‘`#{session_name}:`’ but a different format may be specified with `-F`.

If `-E` is used, the `update-environment` option will not be applied. `-e` takes the form ‘`VARIABLE=value`’ and sets an environment variable for the newly created session; it may be specified multiple times.

## Guides

* [Start a tmux session](https://libtmux.org/en/tmux/guides/getting-started/)
* [Test with an isolated server](https://libtmux.org/en/tmux/guides/testing-with-libtmux/)

## C implementation

Internal declarations in tmux 3.7c:

* [`cmd_new_session_entry`](https://libtmux.org/en/tmux/3.7c/reference/c-variable-cmd_new_session_entry/)
* [`cmd_new_session_exec`](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd-new-session-c-cmd_new_session_exec/)

## Use from a library

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

* [Scala](https://libtmux.org/en/scala/latest/reference/io-github-libtmux-scaladsl-server-newsession/)
* [Kotlin](https://libtmux.org/en/kotlin/latest/reference/io-github-libtmux-kotlin-server-newsession/)
* [Python](https://libtmux.org/en/py/latest/reference/libtmux-server-new_session/)
* [TypeScript](https://libtmux.org/en/ts/latest/reference/server-server-newsession/)
* [Rust](https://libtmux.org/en/rs/latest/reference/server-server-new_session/)
* [Go](https://libtmux.org/en/go/latest/reference/tmux-server-newsession/)
* [Java](https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server-newsession/)
* [C#](https://libtmux.org/en/csharp/latest/reference/libtmux-server-createsessionasync/)
* [C++](https://libtmux.org/en/cxx/latest/reference/libtmux-server-new_session/)
* [Swift](https://libtmux.org/en/swift/latest/reference/server-newsession\(named-startdirectory-windowname-width-height-\)/)
* [Ruby](https://libtmux.org/en/ruby/latest/reference/libtmux-server-new_session/)
* [Lua](https://libtmux.org/en/lua/latest/reference/libtmux-server-new_session/)

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-new-session.c#L39)

```
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.
```