Changing the Starting Directory of a tmux Session

1. Overview

The abbreviation Tmux stands for terminal multiplexer. Terminal multiplexers are command-line utilities that enable control over many virtual terminal windows or SSH sessions from a single terminal window.

Notably, when we start a new Tmux session, it opens up in the current working directory. However, we can modify this behavior for new and current sessions.

In this tutorial, we’ll learn how to change the starting directory of a tmux session in Linux.

2. Setting the Starting Directory for New Sessions

Generally, new Tmux sessions start in the current working directory. However, we can set a preferred directory for a new tmux session using the -c flag.

To illustrate, let’s start a new tmux session foo in the ~/Documents/ directory:

$ tmux new -s foo -c ~/Documents/

Here, the -s flag enables us to name our session foo. Further, the -c option instructs tmux to open in the ~/Documents directory. Notably, the tmux new command is the shortened version of tmux new-session.

Now, we can check our current directory using pwd:

$ pwd
/home/user/Documents

To test the change, let’s detach from the session using the key binding, Ctrl+b, then d.

At this point, let’s re-attach to the session using the attach-session command and the -t flag:

$ tmux attach-session -t foo

After running the command, the tmux session re-opens in the ~/Documents directory:

$ pwd
/home/user/Documents

This shows that the change persists until we exit the session using exit within the session.

3. Changing the Starting Directory in Older Versions

In Tmux versions older than 3.2, we can change the starting directory of a session using the default-path option. To do this, we can either start a new session or attach to an existing one.

3.1. Current Session

To start a new session, we’d simply type tmux in the terminal and press Enter. However, for an existing session, we often use the list-session command to check the available sessions:

$ tmux list-sessions
foo: 2 windows (created Tue Aug  25 14:25:48 2023)

In this case, we see our session foo.

Next, using the tmux attach-session command and the -t flag, we can attach to the session foo:

$ tmux attach-session -t foo

Now, let’s set up the new directory.

Once inside the session, we’ll press Ctrl-b followed by a colon (:). This brings up the Tmux command prompt at the bottom of the screen.

Next, at the prompt, let’s change the starting directory via the set-option command and the global (-g) session default-path option:

:set-option -g default-path /path/to/desired/directory

Here, the /path/to/desired/directory should be replaced with the absolute path of the directory we want to set as the starting directory.

For example, we can have /home/user1/Projects as our initial path:

:set-option -g default-path /home/user1/Projects

Once we press Enter, the set-option command sets the starting directory for the current session.

Notably, changing the starting directory of an already running session affects only the session in question. It won’t affect other sessions or new sessions that we create in the future. Thus, the change only applies to the specific session we modify.

3.2. All New Sessions

Indeed, we can make a directory path persist as the starting directory for new sessions. To permanently apply this change for future sessions, we’ll add the command to ~/.tmux.conf configuration file:

$ echo 'set-option -g default-path /home/user1/Projects' >> ~/.tmux.conf

Importantly, the >> double greater-than signs ensure the command appends the output of echo to the file. Thus, we don’t overwrite any content.

Now, let’s verify the configuration using the cat command:

$ cat ~/.tmux.conf
set-option -g default-path /home/user1/Projects

At this point, we can test the new default starting directory by reloading the Tmux configuration using the tmux command with the source-file argument:

$ tmux source-file ~/.tmux.conf

This command reloads the configuration from our modified ~/.tmux.conf file. Following the reload, let’s test our change.

We can either create a new session or detach (Ctrl-b then, d) and reattach to an existing session:

$ tmux attach-session -t foo
$ pwd
/home/user1/Projects

Indeed, we’ve changed the starting directory of a session in Linux. The specified directory will be the default directory whenever we create or attach to this session in the future.

4. Changing the Starting Directory in Current Versions

Unfortunately, the default-path doesn’t work on Tmux versions 3.2 and above. The Tmux change documentation page highlights the default-path option as incompatible.

In particular, if we set up the ~/.tmux.conf file with the default-path command like before and then proceed to call tmux, we get an error message:

/home/user/.tmux.conf:1: invalid option: default-path

However, we can change the starting directory in newer versions using the new-session command which accepts the -c flag to perform the same function as default-path.

To demonstrate, let’s set the starting directory of a session to /home/user2/Projects.

4.1. Current Session

In the Tmux command prompt, we can change the starting directory for a session. To do this, let’s invoke the command prompt using Ctrl+b followed by (:) and type the command:

:new-session -c /home/user2/Projects

After we key in the command and press Enter, the session opens in the specified directory. However, this change is in effect only for the duration of the session.

4.2. All New Sessions

So, to make the change persistent, we can add a new command to the ~/.tmux.conf file:

$ echo 'new-session -c /home/user2/Projects' >> ~/.tmux.conf

Here, we add new-session -c /home/user2/Projects as a new line to the tmux configuration file.

Next, let’s apply the changes using source-file:

$ tmux source-file ~/.tmux.conf

Again, this reloads the configuration from the modified ~/.tmux.conf file.

Alternatively, we can use the Tmux prompt to reload the changes:

:source-file ~/.tmux.conf

Once we press Enter, Tmux executes the commands in the source file.

We can test the change as we did before:

$ tmux attach-session -t foo
$ pwd
/home/user2/Projects

Evidently, our modifications are applied.

5. Conclusion

In this article, we saw how to change the starting directory of a Tmux session in Linux.

First, we changed the starting directory for a new session. Next, we saw how to change the starting directory in older Tmux versions and make the change permanent.

In addition, we discussed a new way to do the same in a newer version of Tmux.