Vim (Vi IMproved) for Mac OS X

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 started the Macintosh port, including the port to Mac OS X.
• Axel Kielhorn contributed to the Macintosh ports (Classic and Carbon).
• Muraoka Taro, Peter Cucka, Ben Fowler, Eckehard Berns, and others have worked on the Mac OS X version.
• This site, including some of the binaries here, is maintained by Benji Fisher. 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

1. Why do I get error messages about menus every time I start vim? The binaries distributed from this site include a system gvimrc file that redefines the menus. Unfortunately, this does not work if you use menu translations. Either delete the file $VIM/gvimrc (the system gvimrc file) or edit it and uncomment the line

   	  " finish
   

   so that it looks like

   	  finish
   

2. What can I do if vim renders fonts badly, or antialiasing does not work? With vim 7.0, there is a new binary option, 'macatsui'. With

     	:set macatsui
   

   (the default) you will get better rendering of some Unicode characters, but there are still some problems with the code. With

     	:set nomacatsui
   

   vim will render fonts mostly the same as in version 6.4. It may also help to choose a different font (see below). Other options that may make a difference include 'encoding', 'termencoding', and 'antialias'. Several users report that

     	:set nomacatsui anti enc=utf-8 termencoding=macroman gfn=Monaco:h13
   

   works well; others find that

     	:set macatsui enc=utf-8 gfn=Monaco:h13
   

   works better (but loses antialiased fonts). If you set 'nomacatsui', then you should probably also set 'termencoding' to "macroman". If you run vim in a terminal as well as in the GUI, you should probably set these options in your gvimrc file, and use the defaults when running in a terminal.
3. 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.
4. 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 may 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.)

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. -->
5. 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!)
6. 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'
7. How do I change the font?
   (Thanks to Gregory Seidman.) If you use a font-selection dialogue, make sure to choose a monospaced font. For me, the dialogue does not close when I double-click a font, and there is no "OK" button, but if I close the dialogue then the currently selected font is used. Either at the command line or in your vimrc file (or gvimrc file or ...) you can use this command:

   	:set gfn=Courier:h12

   (Trivium: the h stands for "height.") Of course you can choose values other than Courier and 12, such as
   :set guifont=Bitstream\ Vera\ Sans\ Mono:h14
   (Note how to escape spaces.) 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.)
8. 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. Do not use this shell script if you want the shell to wait for vim to finish (for example, when using vim from an e-mail program).
9. How can I use national characters when running vim in a Terminal window? I get funny characters or extra white space!

   (Thanks to Peter Vohmann for this Q&A.) In Terminal.app go the the Terminal (main) menu and choose Window Settings. Select Emulation from the popup menu, un-check the item "Escape non-ASCII characters". Then select Display from the popup menu, set Character Set Encoding to Unicode (UTF-8), if desired. Click on "Use settings as Default."

   And last, vim defaults 'encoding' to latin1. To use Unicode instead, add set enc=utf-8 to your vimrc file or else add the following line to your .bashrc, then open a new shell:
   export LC_CTYPE=en_US.UTF-8

10. How do I get colors in Terminal vim?
    Update: I think this is only a problem for Mac OS X versions 10.0 and 10.1.
    According to Rajesh Duggal, the termcap database that comes with Mac 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 Mac OS X 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.
11. 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'
    
12. Why does vi act like vim on Mac 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. 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. This is what the gvim shell script does, so if you do not want vim to fork (for example, to use it from a mail client) you should use the full path to the binary.
3. I have received one report of two new bugs when running Vim on Tiger (Mac 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.
4. Modifier keys are not handled properly. For example, CTRL-6 seems to behave exactly the same as 6.
5. The Vim menu cannot be changed with :menu commands, and the "About Vim" item does nothing.
6. 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.
7. Encoding is not always recognized (e.g. :set fileencoding=latin1), resulting in MacRoman output instead of the specified encoding. Update:Mac 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).
8. It seems that we need separate binaries for Mac OS X 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.
9. 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.
10. Some wish-list items: live resize (i.e. the whole window redraws while the user resizes it); printer dialogue; draf-and-drop editing.
11. 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.

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 Mac 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

There are several experimental and otherwise unofficial patches available on the Mac Vim wiki. The binaries available here may incorporate some of these; see the notes for each binary. After suitable testing, these patches may be added to the official vim sources.

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.

Last updated: 2007/06/28 06:47:14 PDT