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.