tmux new session: create, name and start detached

tmux new-session -s name (alias: tmux new -s name) creates a session called name and attaches to it immediately. Add -d to create it without attaching, and -c path to set the directory it starts in. Running bare tmux does the same thing with an auto-generated numeric name, which is fine for a throwaway session and annoying for anything you plan to come back to.

Named vs unnamed sessions#

tmux with no arguments creates a session named 0, or the next free integer if 0 is taken. That works right up until you have three of them and tmux ls shows:

0: 1 windows (created Mon Jul 14 09:12:41 2026)
1: 1 windows (created Mon Jul 14 09:14:02 2026)
2: 1 windows (created Mon Jul 14 09:15:47 2026)

None of that tells you which one is running the deploy and which one is htop. Name it at creation time instead:

tmux new -s deploy
tmux new -s scratch

Now tmux ls reads deploy: 1 windows... and scratch: 1 windows..., and tmux attach -t deploy does what it says. Naming costs nothing at creation time and saves real time every attach after that — see tmux attach session for what you do with the name once you have it.

Creating a session without attaching: -d#

tmux new -s ci -d creates the session and returns you to your current shell instead of switching into it. This is the form you want from a script, a cron job, or anywhere you are bootstrapping a session you will attach to later — or never, if it is just running a build.

Without -d, tmux new -s ci would have taken over your terminal, which is wrong for a CI-style session you want to keep polling with tmux capture-pane rather than sit in front of.

Choosing the starting directory: -c#

By default a new session starts in whatever directory you ran tmux from. -c overrides that:

tmux new -s work -c ~/projects/api

This matters more than it sounds like once you have a dotfiles script creating several sessions from $HOME — without -c every one of them starts in your home directory and you cd manually into each one. -c also accepts - in attach-session/switch-client to reuse the current client's directory, but for new-session you give it a real path.

Naming and renaming#

You can rename a session two ways: at creation with -s, or after the fact with rename-session (shell command) or prefix $ (key binding, while attached):

Renaming does not touch the windows or panes inside — it only changes the label tmux and every other command uses to refer to the session.

Naming a window at the same time#

-n on new-session names the initial window, which is worth doing if you already know what it is for:

tmux new -s work -n editor

That gives you work:editor instead of work:0, one step ahead of the renaming you would otherwise do with prefix ,.

Creating sessions from a script#

The pattern that actually matters for automation is "create this session if it does not exist, attach to it if it does" — you do not want a bootstrap script to fail with duplicate session every time you re-run it. new-session -A does exactly that:

tmux new-session -A -s work

-A makes new-session behave like attach-session when the session already exists. Run it once and you get a fresh session; run it again from the same or a different terminal and you attach to the one already running.

For anything with more than one window, has-session as an explicit guard reads more clearly:

has-session exits 0 if the session exists and non-zero if it does not, which is exactly the shape a shell && guard wants. This same pattern is worth stealing for any dev-environment bootstrap — see the scripting section of tmux commands for more of it.

The error you will actually hit: duplicate session#

Creating a session with a name that already exists does not silently attach you to it — it refuses:

That is tmux new-session, not -A. Either attach instead (tmux attach -t work), pick a different name, or use tmux new-session -A -s work if you want "create or attach" behaviour without checking first.

Checking on a session you just started#

-d sessions are easy to lose track of, especially a long build kicked off before you left for the day. tmux capture-pane -p -t ci from another terminal will print the pane's current contents, which is the honest way to check on it without a second tool. If you would rather get told the moment it finishes instead of polling, that is what mtmux is for — it attaches to sessions you already created with tmux new -d and pushes a notification when a pane goes quiet or a command exits, on your phone or in a browser tab.