Vim (Vi IMproved) for Mac OSX

OS X 10.4 (Tiger)

OS X 10.3 (Panther)

OS X 10.2 (Jaguar)

Credits

• Bram Moolenaar is the primary author of Vim.
• Dany St-Amant did almost all of the work for the Macintosh port, including the port to OS X.
• Axel Kielhorn is working on the Macintosh ports (Classic and Carbon).
• Muraoka Taro, Peter Cucka, Ben Fowler, and Eckehard Berns have worked on the OSX version.
• This site, including some of the binaries here, is maintained by Benji Fisher. That is all I do: I am not competent to program for the Mac, and I cannot implement new features nor fix bugs in vim.

Support

• For general information on Vim, see VimOnline.
• To join the Vim users' mailing list or the vim-mac mailing list, see these instructions.
• You can see the documentation on-line at VimOnline, or type
  :help
  inside Vim.
• If there is a problem with this site or the binaries here, e-mail me.

FAQ

• How can I use multiple top-level windows? If you just want separate copies of Vim.app running, without communicating with each other, either use the gvim.app application bundled with the binary distributions or else see the question How do I start vim from Terminal? below. If you want one instance of Vim.app running with multiple top-level windows, this cannot be done. There are serious design issues to be considered, and implementation would probably be very difficult. This feature has been requested often, and not just for the Mac version of Vim. See the voting list for vim features. The appropriate place to discuss this is the vim-dev mailing list.
• I changed Info.plist so that Vim.app could be the default for my favorite file type, but it still does not work! What do I do next?

  The following instructions from Peter Cucka are written for the gvim.app helper application, but they should also apply to Vim.app itself.

  It might take some work to get the Finder to recognize the new Info.plist. If my reading of this document is correct, there are two ways to do this. One is to replace your old /Applications/gvim.app with the new version and then reboot your Mac. The other is to create a new directory somewhere, untar the attached archive into it, and then navigate to the new directory from the Finder (you might also need to restart the Finder, or log out and back in again).

  If the new gvim.app has been registered correctly, it should appear in the Open With list for all files with a .txt extension. To associate gvim.app with .c (or other) files, you will need to Get Info on a .c file, search for gvim in the Open With list and Add it, and then Change All to make gvim the default app. All .c files will then open with gvim (but, oddly, gvim still won't show up in the Open With list; if you want it to, you'll have to edit the Info.plist file to register a new .c document type.)

• How can I use a scroll mouse? This should work properly with recent binaries from this site, or any version compiled with patch 6.2.290. Michael Johnston reports that the shareware USB Overdrive works with vim and a scroll wheel.
• How do I map the Apple key? You can map the Apple (Command) key with the prefix <D->. For example, in the gvimrc file that I supply, I use <D-s> for the Save command and <D-S-s> for the Save As ... command. Note that, in the current version, neither <D-S> nor <D-S-S> will work. (Thanks to Axel Kielhorn for working on this!)
• How can I keep file creators and other meta data when I save a file with vim?
  If you
  :set backupcopy=yes
  then you can edit files with Vim without changing their creator codes, so that opening them from the Finder will still launch the application that created them. New files that you write with Vim will still get Vim's creator code. For details, read
  :help 'backupcopy'
• How do I change the font?
  (Thanks to Gregory Seidman.) The current version does not support standard font-selection dialogues, so you must do this, either at the command line or in your vimrc file (or gvimrc file or ...):
  :set gfn=Courier:h12
  (Trivium: the h stands for "height.") Of course you can choose values other than Courier and 12.
  You can get a list of monospaced fonts on your system from Mail.app: in the Preferences, choose the Fonts & Colors pane. On my system, the available fonts are Andale Mono, Courier New, Monaco, and Osaka-Mono. (Thanks to John Ingram for this tip.)
• How do I start vim from Terminal?
  Warning: case matters! If you use vim when you are supposed to use Vim (or vice-versa?) it may fail in odd ways.
  You can start the GUI version from a shell using the open command. (man open: fans of the NeXT will remember this one!)
  % open -a Vim
  % open -a Vim foo.txt
  You can also use this binary in a Terminal window. Change the path to Vim.app as appropriate:
  % /Applications/Vim.app/Contents/MacOS/Vim foo.txt
  Finally, you can start the GUI version the same way, adding the -g flag (and others if you like). Run it in the background if you want the shell to accept further input before quitting Vim.
  % /Applications/Vim.app/Contents/MacOS/Vim -g +17 foo.txt &
  To make this simpler, I supply the gvim shell script in my distribution. If you put it in your path, then
  % gvim +17 foo.txt
  does the same thing. (Thanks to Bram Moolenaar for the script.)
• How do I get colors in Terminal vim?
  Update: I think this is only a problem for OS X versions 10.0 and 10.1.
  According to Rajesh Duggal, the termcap database that comes with OS X is incorrect. There are two solutions: you can edit the termcap database (which requires superuser privileges) or you can add some extra lines to your vimrc (or other startup) file. Another theory is that the right terminal type for Terminal.app is Beos-Ansi.
  1. (Rob Griffiths) Try
     :set term=builtin_beos-ansi
     This requires that your version of vim was compiled with support for this terminal type. If it works, add a line like this (with or without the leading : character) to your vimrc file. For further details, see Mac OS X Hints.
     On OSX 10.2 (Jaguar), :set term=ansi may work better. I have some reports that builtin_beos-ansi works and some reports that it does not. Both work for me, but with different colors.
  2. (Rajesh Duggal) Edit the termcap database:
     1. % sudo vim /usr/share/misc/termcap
     2. Add the second of these lines between the other two, which should already be there:

        	d0|vt100|vt100-am|vt100am|dec vt100:\
        		:Co#8:Sf=\E[3%dm:Sb=\E[4%dm:\
        		:do=^J:co#80:li#24:cl=\E[;H\E[2J:sf=2*\ED:\
              

     3. Reconstruct the database with

        	% sudo cap_mkdb /usr/share/misc/termcap
              

     4. Quit and restart Terminal, and you'll pick up the new termcap entry.
  3. (Jens Vagelpohl) Add lines something like the following to your vimrc file:

     	  if !has("gui") && has("terminfo")
     	    set t_Co=16
     	    set t_AB=^[[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm
     	    set t_AF=^[[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm
     	  else
     	    set t_Co=16
     	    set t_Sf=^[[3%dm
     	    set t_Sb=^[[4%dm
     	  endif
         

     Note that "^[" should be replaced by a raw Escape character.
• How can I edit old-style Mac files?
  Add a line like
  :set ffs+=mac
  to your personal vimrc file. For more information,
  :help 'ffs'
  
• Why does vi act like vim on OS X 10.3 (Panther)?
  Starting with this version, Apple includes a terminal-only (that is, non-GUI) version of vim in their system. Apple makes /usr/bin/vi a link to /usr/bin/vim and includes a system vimrc file (last I checked, it was /usr/share/vim/vimrc) that sets 'nocompatible'. If you remove this file, and do not have your own vimrc file, then vi and vim will run in compatible mode.

Known Bugs

Here are the problems that bug ME the most:

1. Several users report that certain options are mysteriously set to non-default values: usually the 'wrap', 'diff', and related options. (If your Vim.app starts up in diff mode, with a gray fold column at the left of the window, you are probably affected by this bug.)
   There is a workaround: add "set wrap" to your personal gvimrc file; if that fails, add
   autocmd VimEnter * set wrap
   to either your vimrc file or your gvimrc file. (Replace wrap with whatever option is misbehaving.)
2. I have received one report of two new bugs when running Vim on Tiger (OS X 10.4):
   • When the lazyredraw and showcmd options are both set, screen updates are very slow.
   • With some fonts (Monaco:h10 for example) bold text renders badly. This may be a problem only for fonts that do not have bold variants, so that QuickDraw has to generate the bold variants.
3. Modifier keys are not handled properly. For example, CTRL-6 seems to behave exactly the same as 6.
4. The Vim menu cannot be changed with :menu commands, and the "About Vim" item does nothing.
5. Scroll bars (reported by Jay Lawrence and others):
   • not updated when resizing windows: That is (I think) if you resize the GUI window, then immediately fiddle with the "thumb" or with the scroll arrows, nothing happens. If you click in the text area first, then it is OK.
   • After :set go+=l, the scroll bar does not appear unless the window is resized. After :set go-=l, the columns used by the scroll bars are not reclaimed.
   • After :set go+=b, there is space for the scroll bar but nothing visible unless the window is resized.
6. Encoding is not always recognized (e.g. :set fileencoding=latin1), resulting in MacRoman output instead of the specified encoding. Update:OS X 10.3 (Panther) comes with iconv, so versions compiled with "big" features should deal with encoding correctly. There are still some display problems, but there is already a patch available (experimental as of Feb. 23 2004).
7. It seems that we need separate binaries for OSX 10.1.x and 10.2. I think this has to do with different versions of gcc. Versions of vim that are linked to external libraries (such as the libraries for perl and python) will only run on one of 10.2 or 10.3.
8. There is no support for a font-selection dialogue. (See the FAQ list above for a work-around.) Update: Peter Cucka has made a patch to support file-selection dialogues. The problem is that it does not restrict you to fixed-width fonts, and you can get into real trouble with a proportional font. I have decided not to make it easy to get into trouble, so I do not use this patch in the versions I distribute.
9. Some wish-list items: live resize (i.e. the whole window redraws while the user resizes it); printer dialogue; draf-and-drop editing.
10. Keyboard shortcuts in menu items get lost. Thanks to the patch from Peter Cucka, the following works:
    :nmenu 20.360 &Edit.&Paste<Tab><D-v> <D-v>
    That is, not only does Command-v get executed by this menu item, but a pretty Command-v symbol appears in the menu, right justified. However, if I put regular text, like "\t", after the "<Tab>" then it gets lost. Can we at least translate "<Tab>\t" into "  \t"? That is, I will be satisfied with a little white space, I do not insist that it be right justified.
11. Forking is non-standard. When starting Vim from Terminal.app with the -g flag, the -f flag is ignored. IIUC, the default behavior is not to fork: the shell waits for Vim to finish before it can do anything else. You can simulate forking by running Vim in the background.

Other Versions

• For other operating systems, see VimOnline.
• For Classic Mac OS, see Axel Kielhorn's page.
• For a Terminal or XDarwin version, see Marc Liyanage's Mac OS X Software page. IIRC, I used the Terminal version from this page with no problems. I did not test the XDarwin version.

Compiling for Yourself

On OS X, make install will, by default, create Vim.app. You can also compile a Terminal version of Vim pretty much the same as for any other version of UNIX. See the FAQ section above for information on getting colors. I have not tried using gvim with XDarwin, but have seen reports that it works. (See the links above.)

The following subsections describe how to get the sources, configure, and compile. They also describe the differences between the standard distribution and the binaries above. Note that these instructions only apply to vim version 6.2.128 (that is, vim 6.2 with the first 128 patches) and later.

Getting and patching the source

I recommend using CVS to get the source with all the latest patches. (Well, sometimes the CVS version lags by a few days.) See www.vim.org for details. Here are the results when I try it:

  % cvs -z3 -d:pserver:anonymous@cvs-pserver.sf.net:80/cvsroot/vim checkout vim
  cvs server: Updating vim
  U vim/BINARY.files
  U vim/Contents
  U vim/Contents.info
  U vim/FIND.BINARY.sh
  U vim/Makefile
  U vim/README.txt
	[many lines deleted]
  cvs server: Updating vim/src/xxd
  U vim/src/xxd/.cvsignore
  U vim/src/xxd/Make_amiga.mak
  U vim/src/xxd/Make_bc3.mak
  U vim/src/xxd/Make_bc5.mak
  U vim/src/xxd/Make_cyg.mak
  U vim/src/xxd/Make_djg.mak
  U vim/src/xxd/Make_mvc.mak
  U vim/src/xxd/Make_os2.mak
  U vim/src/xxd/Make_vms.mms
  U vim/src/xxd/Makefile
  U vim/src/xxd/xxd.c

  % cvs -z3 update -d
  ? src/gui_mac.rsrc
  ? src/if_perl.c
  ? src/ObjX_UNIX
  cvs server: Updating .
  cvs server: Updating farsi
  cvs server: Updating farsi/fonts
	[several lines deleted]
  cvs server: Updating src
  M src/feature.h
  P src/version.c
  cvs server: Updating src/GvimExt
  cvs server: Updating src/VisVim
  cvs server: Updating src/VisVim/Res
  cvs server: Updating src/auto
  P src/auto/configure
  cvs server: Updating src/os_mac.pbproj
  cvs server: Updating src/po
  cvs server: Updating src/proto
  cvs server: Updating src/tee
  cvs server: Updating src/testdir
  cvs server: Updating src/xxd

You can get the vim sources from ftp.vim.org or your favorite mirror. (Mine is ftp.rge.com.) You should get the main archive, vim-6.2.tar.bz2 (StuffIt understands bzip archives!) and the "extra" archive, vim-6.2-extra.tar.gz. I also get the "lang" archive, vim-6.2-lang.tar.gz just to make sure that the patches apply cleanly, and all the latest patches. Here is how I get the sources and all patches for vim 6.2:

  % mkdir patches
  % mkdir patches/old
  % ftp ftp.vim.org
  ftp> bin
  ftp> cd pub/vim/unix
  ftp> get vim-6.2.tar.bz2
  ftp> cd ../extra
  ftp> get vim-6.2-extra.tar.gz
  ftp> get vim-6.2-lang.tar.gz
  ftp> cd ../patches
  ftp> lcd patches
  ftp> mget 6.2.???
  ftp> quit
  % bzcat vim-6.2.tar.bz2 | tar xf -
  % tar xzf vim-6.2-extra.tar.gz
  % tar xzf vim-6.2-lang.tar.gz
  % cd vim62
  % cat ../patches/6.2.* | patch -p0

To update the patches, I make a note of my most recent patch and then

  % cd patches
  % ls
  % mv 6.2* old
  % ftp ftp.vim.org
  ftp> bin
  ftp> cd pub/vim/patches
  ftp> mget 6.2.12?
  ftp> mget 6.2.13?
  ftp> quit

Applying unofficial patches and configuring

These are the unofficial patches that I currently use to compile for OSX:

• transparency.diff (6875 bytes, last modified 2004/04/15 12:02:48.771 GMT-5)
  Credits: MURAOKA Taro
  Purpose: Add a 'transparency' option for Windows and Mac GUI versions of vim, with a value of 1 (clear) to 255 (opaque). Do not set 'transparency' too low, or Vim becomes invisible!
  Note: I do not currently use this patch.
  
• TransBack.diff (15272 bytes, last modified 2004/04/15 12:01:11.773 GMT-5)
  Credits: Eckehard Berns
  Purpose: Make the background, but not text and title bar, transparent.
  Note: This makes scrolling the command line slow (try :version). There are redraw problems when the main window is resized. (Update: both problems may have been solved with the 2004-04-04 version.)
  
• conceal-ownsyntax.diff (193170 bytes, last modified 2004/04/15 12:03:49.783 GMT-5)
  Credits: Vince Negri
  Purpose: Allow some characters to be completely hidden, not just transparent.
  Note: See this page for more information.
  

If you want, apply unofficial patches with

  % cd vim62
  % patch -p0 < path/to/patch

You configure vim by editing vim62/src/Makefile. I choose "huge" features and enable as many as I can of perl, python, tcl, and ruby. (As of October, 2003, there are still linking problems with these.) Note that these options are passed to configure: if you have already built vim, then change one of these, you will have to "make reconfig."

Compiling and packaging.

The Makefile for vim takes care of running configure for you, so all you have to do is

  % cd vim62/src
  % make
  % make test
  % make install

Extra files:

• I distribute these runtime files with the Carbon binary: a custom vimrc and gvimrc file, a README, a gvim shell script, and (why not?) updated copies of the distribution files that I maintain. After un-bzip'ing and un-tar'ing these, the two rc files should be put in Vim.app/, the shell script (if you want to use it) should go somewhere in your path, and the other files under Vim.app/runtime/.
• I use the Vim icon designed by Douglas Stebila. See his web page for this and some related icons. If you want to use this, install it as Vim.app/Contents/Resources/gui_mac.icns.

Notes:

1. For more details, see vim62/src/INSTALLmac.txt.
2. Remember to run configure or make reconfig if you change any of the configure options in the Makefile.
3. You can also supply options to the configure command before running make to enable/disable features or to use something other than the Carbon GUI. Try
   ./configure --help
   for details.
4. You can also compile using ProjectBuilder (or pbxbuild from a command line). Try open os_mac.pbproj. I do not use this method myself, so I cannot give further advice.