Save and Restore Vim Editing Sessions with :mksession and :source

You have spent ten minutes arranging Vim exactly the way you need it: a vertical split for reference, a horizontal split for a log file, line numbers enabled in one buffer, and the cursor parked on a specific function. Then you close Vim to install a system update. When you reopen it, you get a single empty buffer and have to rebuild everything from scratch.

Vim's built-in session management solves this. By writing your current editing state to a file with :mksession and replaying it later with :source, you can preserve buffers, window layout, cursor positions, and selected options without installing a plugin.

What a Vim session preserves

A session file is a generated Vim script. When sourced, it reconstructs the editor state that existed when the file was created. In standard Vim builds, this includes the list of open buffers, the window split geometry, cursor positions within each buffer, global and buffer-local options, and user mappings.

Two prerequisites apply. First, Vim must be version 7.0 or later and compiled with the +session feature; this is present in the default builds shipped by most Linux distributions, macOS Homebrew, and Windows installers. You can confirm this by running :version inside Vim and looking for +session, or by running vim --version in your terminal. Second, you need write permission to the directory where you intend to store the session file.

Saving the current state

Arrange your buffers, splits, and options as you want them. Then run the following command inside the affected Vim instance:

:mksession! ~/my-session.vim

The exclamation mark forces an overwrite if the file already exists. Without it, Vim refuses to overwrite an existing session file. The path can be absolute or relative; using a relative path such as ./my-session.vim keeps the session file inside the project directory and makes it easier to version-control alongside your code.

After the command returns, the session file contains Vim commands that will recreate the layout. Close Vim normally.

Restoring the session

Later, launch Vim from your terminal and source the file:

:source ~/my-session.vim

Vim executes the script, reopens the recorded files, and rebuilds the window splits. If you used a relative path when saving, make sure your working directory matches the location expected by the session file, or use an absolute path when sourcing.

A concrete workflow

Suppose you are debugging a web application. You want a session that keeps three files visible.

1. Open the main entry point: :edit src/app.js
2. Split the window vertically: :vsplit src/router.js
3. Split the lower pane horizontally: :split logs/debug.log
4. Enable line numbers in the active buffer: :setlocal number
5. Save the session: :mksession! ./debug-session.vim

After restarting Vim, run :source ./debug-session.vim from the same project root. The three buffers should reappear in the same split arrangement, with line numbers active in the buffer where you enabled them.

Verifying the restore

Do not assume the session restored correctly. Run these checks inside the restored Vim instance:

Check	Command	What to look for
Buffer list	:ls	All expected files appear with their buffer numbers.
Window layout	:windows	The same number of splits and relative sizes.
Cursor position	:echo line('.') . col('.')	Line and column match the saved position.
Local option	:setlocal number?	Output shows number (or nonumber) as saved.

When restoration fails

If sourcing produces errors, Vim records them in the message history. Run :messages to inspect the output. Common causes include a moved project directory, a deleted file, or a plugin that injected temporary buffers during the original save.

To isolate plugin interference, restart Vim with plugins disabled:

vim --noplugin -c 'source ./debug-session.vim'

If the session restores cleanly without plugins, a plugin is likely modifying buffer-local state or creating scratch buffers that the session script cannot recreate.

If the session file itself is corrupted—for example, truncated by an interrupted save—delete it and repeat the :mksession! step from a known-good layout. As a last resort, reopen the files manually and rebuild the splits; session files are a convenience, not a substitute for a reproducible project setup.

Limitations and risks

Session files store absolute paths by default. If you move the project to another machine or a different directory, those paths break and Vim will report missing files. Keep the session file in the project root and use relative paths where possible, or regenerate the session after relocating the project.

Plugins that manage their own temporary buffers, terminals, or fuzzy-finder state may not restore correctly. Test any session that depends on plugins with vim --noplugin if you suspect interference.

Finally, :mksession! overwrites the target file without a confirmation prompt. If you need to preserve an earlier layout, copy the session file to a backup name before saving a new one.