1. Introduction

We definitely appreciate how fast it is to work with Vim compared to GUI-based editors. But, is it really faster if we always have to reconstruct our accustomed layout every time we start working on something?

This is where Vim sessions come to the rescue. A session can remember the window layout, open files, and much more. Hence, we can use it to quickly rebuild the previous state and pick up our work where we left off.

In this quick tutorial, we’ll learn a few tips for working with Vim sessions.

2. Saving a Session

Saving a session in Vim is straightforward. We need to use the :mksession command, or :mks for short:


By default, the session is saved in a Session.vim file in the same directory where Vim was started. If we look inside the file, we’ll see a script with instructions on how to reconstruct the session. What sets it apart from a regular Vim script is the first line:

let SessionLoad = 1

This sets a global variable to indicate that a session is loading.

Furthermore, we aren’t limited to the default session. By providing a file path argument, we can save the session in a different file:

:mksession new-session.vim
:mksession ~/.vim/sessions/new-session.vim

In case a session file with the same name already exists, we can override it with the ! command:

:mksession! new-session.vim

We can save any number of sessions in any location as long as we follow one rule: The file must have the .vim extension.

3. Restoring a Session

Restoring a session can be done in two ways. The first is starting Vim with a saved session, using the default or a named session:

vim -S
vim -S {session file path}

The second option is to restore a session while working in Vim. For that, we use the :source command, or :so for short:

:source {session file path}

Note that the -S option and :source can be applied to any Vim script and aren’t specific to Vim sessions.

4. What Is Saved in a Session?

A session can store many things: windows, layout, buffers with file positions, working directory, options, global variables, and more. Non-empty windows are always saved. What else will be saved is defined in the sessionoptions, or for short ssop, option.

To see what the sessionoptions value is, we use the :set command:

:set sessionoptions?

The result is a comma-separated list of words. Currently, the default value is:


Let’s see what each of these words does:

  • blank keeps empty windows
  • buffers saves all buffers, including hidden and unloaded buffers
  • curdir remembers the current directory
  • folds saves all kinds of code folds
  • help keeps the help windows
  • options remembers all options and mappings, including global values for local options
  • tabpages saves all tab pages
  • winsize saves window sizes
  • terminal includes terminal windows to restore the commands

Similar to options, we have localoptions, with the difference being that it won’t save global values for local options and mappings. We can also save global variables with global.

Also, note that without tabpages, only the current tab page session will be saved. Thus, we’ll be able to work with a separate session for each tab.

We can add or remove words from sessionoptions with :set and += or -= assignment:

:set sessionoptions+=global
:set sessionoptions-=terminal

Lastly, there are some limitations to what sessions can save. For example, if we want to save command line history, registers, or marks, we’ll need to use the viminfo feature instead.

5. Session Use Cases

Now that we’ve learned how to work with sessions, let’s see in what scenarios sessions can be helpful.

The most notable use case is to have a session on a project-by-project basis. This will allow us to quickly switch between projects without much overhead, and without leaving Vim. Moreover, we can have a different session file for different parts of the same project.

Another possible use case is to create a session with our preferred layout and options as a template session. This will act as a starting point for Vim and make it more IDE-like.

Finally, we can use sessions to do more productive collaborative work. Along with sharing the code, we can also share the session file. This way, our teammates can quickly jump to the same point.

6. Conclusion

In this article, we looked at Vim sessions. Saving and restoring a session is a quick way for re-creating our preferred Vim state. In addition, we can configure what will be saved in a session using session options.

Vim’s built-in help will give more information if we run the :help :mksession, :help :source, and :help sessionoptions commands.

Inline Feedbacks
View all comments
Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.