The VIM-Shell



What is VIM-Shell?

The VIM-shell is a extension for VIM, a very popular programmer's editor for many platforms, written by Bram Moolenaar et al. VIM features split windows, and this patch makes it possible to start shells in those windows. It is only available for POSIX systems like Linux, FreeBSD, OpenBSD, NetBSD and MacOS X. I don't think the Windows-VIM needs such a patch, because I think the command line there isn't really popular.

The current version available is 1.0.

But why?

This seems to be a feature that many people want, yet noone wrote such a patch. The official VIM authors don't want to integrate such a feature into the main VIM editor. I understand and fully agree with their point of view, that they don't want VIM to become overbloated with features. I think that is a good decision and a good way to manage the VIM project.

Nevertheless, spawning a shell in a VIM window is something I desperately sought after since the first day I started working with VIM, and searching on Google reveals that I'm not the only person. Someone even hacked together a Python script so you can start a shell in a window, but it's no terminal emulator, so your possibilities with this "shell" are limited. I wanted to have a real, working shell in VIM, so I wouldn't have to switch around with screen, use half-hearty solutions like splitvt etc.

Considering that the main VIM sourcecode is around 250.000 lines of code, the VIM-Shell patch with its 3.000 lines of code really doesn't add much to VIM's codebase. The terminating line between VIM and VIM-Shell is distinct and clean, and it shouldn't interfere with any of VIM's functionality.

Features and Bugs

This really is a full blown terminal emulator that understands "vt100" and "screen" termcaps (the latter one because it's already installed on most of the supported systems), including ANSI colors. The terminal emulation is to 90% complete, but I couldn't find any program out there that wouldn't be rendered correctly by the terminal engine (the most popular tested ones are: mutt, irssi, centericq, make menuconfig and friends, tin, slrn, and of course VIM).

With this patch you can start as many shell windows as you like. You can resize them and rearrange them as you want. With this patch, VIM almost turns into a text mode window manager that additionally can edit files :-)

Note, however, that so far only the text mode VIM is fully supported, but support for the GUI version is on its way.

Mailing List

We have a mailing list, hosted by

Address Description General announcements regrading the VIM-shell, usage of the VIM-Shell and development. archive

We strongly urge you to subscribe to this mailing list if you want to use or try out the VIM-Shell. Please send feedback and bug reports there.


Source code (diff against the official VIM sources (version 6.3+058)):

vimshell_1.0.patch.bz2 (80 KB)

Source code (diff against the official VIM 6.4 sources):

vimshell_1.0_vim6.4.patch.bz2 (100 KB)

Source code (diff against the official VIM 7.0 sources):

vimshell_1.0_vim7.0.patch.bz2 (92 KB)

Installation (from source)

Get the VIM sourcecode either from the VIM homepage or from CVS. After unpacking, step *into* the unpacked directory and apply the patch:

$ tar jxf vim-6.3.tar.bz2
$ cd vim63
$ bzcat ../vimshell_1.0.patch.bz2 | patch -p0

After that, ./configure, make and make install VIM as you need.



How to use the VIM-Shell

This is a small introduction on how to use the new features in your VIM-Shell-enabled VIM.

General concept: ":vimshell"

The whole VIM-Shell functionality is hidden behind one single command: :vimshell.

:vimshell[!] [params] tries to close your active buffer and creates a new one. This behaves exactly the same as the :enew command (see :help enew im VIM for details). If you have local modifications to your buffer, the command will be aborted (but you can override this by adding a ! at the end, in this case the active buffer will be dismissed in any case). The window containing this empty buffer is then converted to a VIM-Shell.


starts a VIM-Shell in your current window. I strongly suggest you open a new window before doing that. By default, without any parameters, /bin/sh will be spawned.

:vimshell bash

When called with parameters, VIM-Shell passes these parameters verbatim to execvp when starting a shell. Your current $PATH will be searched for the command.

:vimshell irssi -n anonymous -c

starts the textmode IRC client "irssi" with the abovementioned parameters.

:vimshell mutt

Never lose track of your e-mails while working in VIM!

When you exit such a shell, or the program running in it terminates, the buffer will be converted back to a normal, empty VIM-buffer. The window will not be closed.


When the currently active window is a VIM-Shell, every character entered gets routed to the shell, and no mapping expansion takes place. VIM doesn't get any notice of the characters that you type in a VIM-Shell.

The big exception is Ctrl_W, which is passed through to VIM, so you can close the VIM-shell (Ctrl_W + c), change to another window, resize the window, etc.

Key mappings

Because I feel that opening up a window and then typing :vimshell is a bit cumbersome, I suggest you use the following key mappings in your .vimrc:

" VIM-Shell
" Ctrl_W e opens up a vimshell in a horizontally split window
" Ctrl_W E opens up a vimshell in a vertically split window
" The shell window will be auto closed after termination
nmap <C-W>e :new \| vimshell bash<CR>
nmap <C-W>E :vnew \| vimshell bash<CR>

Just hitting Ctrl_W and e to drop a shell window in your VIM session is really, really comfortable :-)

Authorship, Credits


The VIM-Shell was written in 2004 by Thomas Wana <>. Please send feedback and bug reports to the list

The VIM-Shell is published under the GNU GPL license (which is compatible with the VIM license). The copyright remains by the author.

I would like to thank...

Wolfgang Hennerbichler ( for hosting the VIM-Shell mailing list and for access to a MacOS X box.

Last update: