Tips And Tricks

Here are some tips and tricks on setting up Emacs.app on Mac OS X. These are based on my personal experience of using Emacs.app for the past 10 years or so; there may be better ways, but these work for me.

Running Emacs.app from the command line

Run this to make a symlink to ensure emacs is in your PATH.

sudo ln -s /Applications/Emacs.app/Contents/MacOS/Emacs /usr/local/bin/emacs

Or, if you prefer Emacs to stay in the terminal instead of opening a new macOS window then there is a small shell wrapper included that forces the Emacs -nw parameter:

sudo ln -s /Applications/Emacs.app/Contents/MacOS/emacs-nw /usr/local/bin/emacs

Using emacsclient

  1. Make sure the latest emacsclient binary is in your path:

    sudo ln -s /Applications/Emacs.app/Contents/MacOS/bin/emacsclient /usr/local/bin

  2. Optionally add alias emacs='emacsclient -c -a ""' or alias emacs='emacsclient -nw -c -a ""' to your ~/.bashrc.

Making sure other terminal programs launch Emacs instead of Vim

Add this to your .bashrc:

export EDITOR="emacs"
export VISUAL="emacs"

Or, if you prefer Emacs to stay in the terminal instead of opening a new macOS window:

export EDITOR="emacs -nw"
export VISUAL="emacs -nw"

Or, if you prefer emacsclient

export VISUAL="emacsclient -c -nw -a ''"
export EDITOR="emacsclient -c -nw -a ''"

Or, …well, you get the picture. Just set those to whatever you want.

Using Emacs as the mergetool for git

Add add this snippet to your .gitconfig:

If you want to use emacsclient, add this snippet instead:

Changing the Modifier Keys

Easy

The easiest way is to use the Customize interface: "M-x customize-group RET ns RET".

Hard

If you don't like Customize and want to do it manually, the following variables control the modifier keys:

Each variable can be set to 'control, 'meta, 'alt, 'super, or 'hyper.

In addition ns-alternative-modifier (and ns-option-modifier) can be set to 'none, which lets it get interpreted by the OS so it can be used to input special characters.

The ns-right-* variables are set to 'left by default which makes them the same as their left counterpart.

Determining If Native Compilation Is Working

If you are unsure if native compilation (native-comp) is working, type C-h f compile RET to bring up Emacs's help on the compile elisp function. If it says

compile is an autoloaded interactive native-comp-function in
‘compile.el’.

then native-comp is working.

Getting Native Compilation Working

In order for native-comp to work, the macOS developer tools must be installed. This means either Xcode or the Developer Command Line Tools. If you have neither installed, the easiest thing to do is open terminal and run:

sudo xcode-select --install

This will pop up a dialog that kicks off the CLI tools install. After it finishes, native-comp should work.

If it is still not working, check the *Async-native-compile-log* buffer for errors. Most likely, the macOS developer tools are not installed or are not the correct version.

For example, on a macOS 11 test machine I was getting this error:

clang: error: invalid version number in '-mmacosx-version-min=11.0'

The culprit was an old version of the developer CLI tools. Worse, software update did not show that there were any newer versions. The solution was to delete the existing dev tools and reinstall them:

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

Verifying the Binary Integrity

This site serves the binaries via SSL and while the binaries are not GPG signed, the application is code signed. You can verify the signature like this:

codesign -dvv /Applications/Emacs.app

Or, if you haven't installed emacs yet, but have mounted the disk image:

codesign -dvv /Volumes/Emacs/Emacs.app

Look for the following in the output:

Authority=Developer ID Application: Galvanix
Authority=Developer ID Certification Authority
Authority=Apple Root CA

"Galvanix" is my consulting partnership and is what I registered my Apple developer account under. If you see that, the binary is intact.

© 2009 - 2026 David Caldwell