Troubleshooting

This troubleshooting guide lists steps to take in order to find the source of some common problems.

Ensure that configuration files are not the cause

Quit MacVim, temporarily rename your rc-files and .vim directory, then restart MacVim and see if the problem persists. If not, then the problem is in some configuration file or a plugin.

(If the problem is in the config files then you can find it by commenting out all lines in the config files and uncommenting one line at a time, restarting MacVim in between to see if the problem reappeared.)

Step-by-step instructions:

1. Open Terminal and type:

   $ cd ~
   $ mv .vimrc old.vimrc
   $ mv .gvimrc old.gvimrc
   $ mv .vim old.vim
   

   (If you do not have one of the files .vimrc, .gvimrc or the folder .vim then the mv command will report an error which you can safely ignore.)

2. Restart MacVim and see if the problem persists.

3. To restore your config files, open Terminal and type:

    $ cd ~
    $ mv old.vimrc .vimrc
    $ mv old.gvimrc .gvimrc
    $ mv old.vim .vim
   

Test the built-in version of Vim

If it is not a problem with the GUI itself, then you can see if the problem also appears in the version of Vim that ships with Mac OS X. To do so, simply open up Terminal and type vim and try to reproduce the problem. If you can reproduce the problem this way then it is not a bug in MacVim. Try asking for help on the vim_use Google Group.

Try a newer version of MacVim

Download the latest snapshot build of MacVim and see if the problem is still there.

Ensure that other rc-files are not the cause

Quit MacVim, temporarily rename all rc-files for whatever shell you are using (.profile, .bashrc, etc.), then restart MacVim and see if the problem persists. Exactly which files to rename depends on which shell you are using. (To be on the safe side you may want to move all files from your home folder into a temporary folder.)

Reset the preferences

Reset the preferences and restart MacVim.

Step-by-step instructions:

1. Open up Terminal and type (read step 3 first!):

   $ defaults delete org.vim.MacVim
   

2. Restart MacVim and see if the problem persists (since the prefs were deleted MacVim may ask about auto-updating again).

3. Step 1 cannot be undone, so you will have to open up the preferences and restore them manually.

Remove MacVim duplicates

Make sure that you only have one copy of MacVim on your computer. Try searching for MacVim.app in Spotlight to find all copies, then delete all but one.

For zsh users

Rename the /etc/zshenv file to /etc/zprofile

If MacVim appears to use the wrong PATH variable, you may have run into a zsh configuration problem. Try the following:

    $ sudo mv /etc/zshenv /etc/zprofile

NOTE: If the system already has a /etc/zprofile, make sure you merge the two files instead of overwriting /etc/zprofile.

The problem is caused by /etc/zshenv, which (somewhat erroneously) resets the PATH for every zsh instance, not just login shells. MacVim, running in a non-interactive shell, gets a PATH variable that has the OS X system paths but is missing user-defined paths.

If the above alone does not work, there is an additional step involved. Set your PATH (or any other variable you may need) in ~/.zprofile. To do that, assuming you have your PATH set in ~/.zshrc, use the command

    $ cat ~/.zshrc | grep "export PATH" >> ~/.zprofile

There is a caveat: when using Terminal.app, the variables present in .zprofile and .zshrc will contain duplicate items. To avoid confusion add typeset -U name_of_the_variable to your .zshrc.

Ask for help

Post your question to the vim_mac Google Group if it is MacVim related. General questions about using Vim should be posted to the vim_use Google Group.

Note that you do not need to subscribe to email notifications when signing up for either of these groups. You can read the groups online if you would rather keep your inbox clean. These groups are moderated so your first post may take up to a day before it arrives to the group (subsequent posts should show up within a few minutes).

Please read the guidelines before posting to either of these groups.