If you want to check out a stable official release version, you can look for the list of Git tags that has the pattern release-<num>. For convenience you can use the following Git command to check out the latest release:

$ git switch --detach $(git tag --list 'release-*' --sort=version:refname | tail -1)

Pre-release releases use Git tags of the pattern prerelease-<num>. For example, in chronological order, you will see release-180, prerelease-180.1, prerelease-180.2, release-181. You could build these if the official release version is a little too old and you would like more updated functionality.

First clone the repo as above, then configure with the flags you want, e.g.:

$ cd macvim/src
$ ./configure

Once this has finished, build the project (optional: pass -j$(sysctl -n hw.ncpu) to build in parallel for faster builds):

$ make

The resulting app bundle will reside under MacVim/build/Release. To try it out quickly, type:

$ open MacVim/build/Release/MacVim.app

To open the terminal version of MacVim, type:

$ MacVim/build/Release/MacVim.app/Contents/bin/vim

To install MacVim, type

$ open MacVim/build/Release

and drag the MacVim icon into your Applications folder.

To clean and rebuild, you can use make clean ; make. If you want to do a more thorough clean and re-configure from scratch, you can use make distclean to destroy everything and start from scratch.

If you are making changes to MacVim, it could be easier to build/test MacVim from within Xcode instead of invoking make. Simply open src/MacVim/MacVim.xcodeproj and build from there. This will also default to building in Debug instead of Release (which make builds in).

If you have an older version of Xcode (older than Xcode 12) that refuses to open the xcodeproj file, you can open src/MacVim/MacVim_xcode8.xcodeproj instead. The xib files are built for the Xcode 8 format, so if you use Xcode 7 you have to manually convert them before you build them.

Note: You have to build MacVim on the command-line using the Makefile once before you try to build in Xcode. This is because the MacVim.xcodeproj build is the last step in the build chain, and relies on Vim having been built separately, and a runtime_folder_list.xcfilelist to be populated by the build. Every time you modify Vim source code (e.g. src/*.c or src/MacVim/gui_macvim.m), you also have to build Vim separately before building the xcodeproj. You can do that by just running make, or build only Vim by running the following:

$ cd src; make Vim

If you are building for legacy macOS versions (10.9 - 10.12), they should still work but some features may be missing. In particular, only Sparkle 1 is supported. Make sure you either disable Sparkle or configure MacVim to use Sparkle 1 (see below instructions), as the default (Sparkle 2) will not work as it requires 10.13 or above.

Also, note that currently MacVim is only build-able with Xcode 8 or above (due to usage of new Objective C features, and xib files saved in Xcode 8 formats), which is only available for macOS 10.11. If you want to build a binary for 10.9 - 10.10, you will need to build it on macOS 10.11 or newer, but set the deployment target to 10.9.

You can enable extra Vim features by passing the appropriate flags to configure. You don't really need to turn on any flags unless there are specific features you want. These are the parameters to configure you may want to enable:

• Vim binary only (does not affect the GUI app):
  • All standard features (this is turned on by default and only for reference): --with-features=huge
  • Cscope support: --enable-cscope
  • Scripting support:
    • Python interpreter: --enable-python3interp
    • Ruby interpreter: --enable-rubyinterp
    • Perl interpreter: --enable-perlinterp
    • Allow both Python 2 and 3 scripts to be run (see )
    • macOS deployment target (the minimum macOS version that can run the built app): Instead of a configure flag, set environment variable MACOSX_DEPLOYMENT_TARGET=$VER when running configure and make ($VER examples: 10.15, 13.0, …).
      • Example (targeting 10.13): MACOSX_DEPLOYMENT_TARGET=10.13 ./configure; MACOSX_DEPLOYMENT_TARGET=10.13 make.
    • macOS SDK version: --with-macsdk=$VER ($VER examples: 10.15,13.0,…). The SDK needs to be installed. If you want to use older SDKs than the one bundled in Xcode, you can copy them from older versions of Xcode into /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/. You can use otool -l src/MacVim/build/Release/MacVim.app/Contents/MacOS/*Vim | grep sdk to confirm that it's built using the correct SDK.
  • Sparkle (this is the software updater MacVim uses to keep itself up to date):
    • Disable Sparkle:
      1. Run configure with --disable-sparkle. Build as normal.
    • Use Sparkle 1. By default MacVim uses Sparkle 2, which has higher OS requirements than Sparkle 1.
      1. First, change the Sparkle.framework symlink: ln -fsh Sparkle_1.framework src/MacVim/Sparkle.framework
      2. Run configure with --enable-sparkle-1
  • Debugging support:
    • Build Vim with debugging info / without optimizations: Set CFLAGS="-g3 -O0" when calling configure.
    • Build MacVim in Debug configuration when built from command-line: --with-xcodecfg=Debug.
    • To combine both: CFLAGS="-g3 -O0" ./configure --with-xcodecfg=Debug

  To see all available flags, type ./configure --help.

  Easiest way to clean all configured results is by using make distclean which will remove all built binary and configuration and you can call configure again from a clean slate.

  Debugging MacVim

  If you would like to debug MacVim using Xcode, you first have to build Vim using make Vim, then open src/MacVim/MacVim.xcodeproj and you can build, run, and debug MacVim code from within Xcode. See above. Also, see this document for more info of how the code is structured.

  If you would like to debug the Vim process instead (MacVim hosts each window in a separate Vim process and talks to them via Distributed Objects), do the following for best results:

  1. See "Debugging support" above for how to configure MacVim to be built with debugging symbols without optimizations.
     • Alternatively, if you don't want to re-run configure, build using make "CFLAGS=-g3 -O0" XCODEFLAGS="-configuration Debug".
  2. Turn off QuickStart in Advanced Preferences. When that option is on there is a shadow Vim process which makes it more annoying to figure out one is the one you want to debug.
  3. Run MacVim from Xcode, wait for the Vim window to show up.
  4. Find out the PID of the Vim process by running the following in the MacVim source folder: ps aux | grep "`pwd`.*/Contents/MacOS/Vim" | grep -v grep. The first number you see is the PID.
  5. In Xcode (it should already be debugging MacVim itself), select Debug → Attach to Process by PID or Name, and paste in the PID of Vim. Xcode should now be able to debug and set breakpoints within the Vim process.

  For simplicity and efficiency, you can combine step 4 and 5 instead a single convenient command:

  ps aux | grep "`pwd`.*/Vim" | grep -v grep | cut -w -f 2 | tee /dev/tty | pbcopy && osascript -e "tell application \"Xcode\" to attach active workspace document to process identifier `pbpaste` suspended false"

  Localization

  MacVim is localized in multiple ways. Vim itself uses the $LANG environmental variable to determine its message translations and menu language, and MacVim on the app level uses system language to determine overall app localization (which affects some of the menu items as well). You can force MacVim to run in another language. Here is an example to run it in Traditional Chinese:

  LANG=zh_TW.UTF-8 open src/MacVim/build/Release/MacVim.app --args -AppleLanguages '(zh-Hant)'

  MacVim Tests

  MacVim has two types of tests:

  1. Vim tests
  2. MacVim tests

  For (1), they are inherited from Vim upstream. MacVim exists as a fork of Vim, and the Vim tests allow us to verify that the Vim functionality still works as intended. These tests primarily test the functionality in the Vim binary itself. To run these tests, run cd src; make test in the terminal. For more information on Vim tests, refer to Vim documentation. For development purposes there is usually no need to run these tests locally as they mostly catch issues when a bad upstream merge happens.

  For (2), the MacVim tests are written using Apple's XCTest framework. These test the MacVim app binary, and exercise the MacVim GUI functionality and its integration with Vim. To run the tests, either run cd src; make macvim-tests in the terminal, or open MacVim.xcodeproj and build/run the tests directly from Xcode. The tests require MacVim to have been built first.