Binaries for OS X

The official Emacs fully supports Mac OS X (along with GNU/Linux, Windows, DOS, and then some). You can find precompiled versions of emacs and Emacs.app at http://emacsformacosx.com/.

A copy of GNU Emacs 22 without GUI support compiled in is available on all recent versions of Mac OS X via the shell. However, there are other Emacs distributions geared towards Mac OS X that include GUI support as well as other distinctions that may make it a more appropriate choice for some.

Cocoa is the Objective-C API (originally developed by NeXT) that is used for native OS X applications (included in Emacs 23.2). Aquamacs and Emacs.app (which was merged into the official Emacs as of Emacs-23) both run under Cocoa. Note that Emacs.app, GNU Emacs/Cocoa, and GNU Emacs/nextstep refer to the same thing.

Carbon is the C language API (developed by Apple) that lets applications written under OS 9 (or earlier) run under OS X. Carbon Emacs runs under Carbon. As of Emacs 23, Carbon Emacs has been deprecated in favor of Emacs.app.

X11 Emacs is the “original” emacs running under X11 (installed by default in recent versions of Mac OS X)

If you are a Mac user new to Emacs, many people find Aquamacs to be a good choice. Many find it to be more Mac-like than Emacs.app. If you’ve used Emacs before and already have your own Emacs initialization file, then Emacs.app is likely a better choice.

As compared to Aquamacs, Emacs.app is more traditional in its approach, prefers a single frame, and is more likely to work with existing emacs initialization files. When using the vanilla EmacsforOsx binary, a useful site for setting, at least, Emacs server and Emacs client applications is Configuring Emacs on Mac OS X. Emacs shell environments behave differently from Terminal environments and in order to have correct environments like LANG=en_GB.utf-8 LC_ALL=en_GB.utf-8 or PATH= for sub-applications launched from Emacs like R, Octave, Gnuplot etc., set the environments not only in .bash_profile but in .bashrc and try (since Yosemite /etc/launchd.conf is no more consulted for security reasons).

If you are looking for more integration with OSX, Mitsuharu Yamamoto’s Mac port might be the best option. It adds valuable smooth scrolling and subpixel font rendering not found elsewhere. Other than that is it stock standard emacs.

OS X Binary Vanilla builds

These builds are based on the development version of GNU Emacs and do not contain any additional packages or patches. Popular Mac keyboard shortcuts are available though (e.g. Command-O for opening a file); these are mapped to the Super modifier (i.e., the Apple/Command key functions as Super).

OS X Distributions with extras

Custom distributions contain startup routines and tweaks to make Emacs’ UI behavior more “Mac-like”. In addition to that, they typically include recent versions of popular packages.

Building Emacs From Source

Getting the Source


To download emacs using git, use this command:

    git clone git://git.savannah.gnu.org/emacs.git


Available from the GNU Savannah emacs page. Click on “Download Area” under “Quick Overview”.

Building Emacs for OS X, using the normal GUI

There are many options for building emacs (such as whether to build for the X11 GUI or the Cocoa GUI), which are discussed in the INSTALL file. There is also a script (emacs/mac/make-package) to create a Mac OS X package for use by the installer.

The “normal” way to build Emacs under Mac OS X is:

  ./configure --with-ns 
  make install

When the build is complete, you should see Emacs.app in ./nextstep/Emacs.app. Simply copy it to your applications folder and open it to run.

For more detailed instructions, see the nextstep/INSTALL file. Additionally, you may benefit from reading the build script here: http://github.com/ieure/emacs-nightly. As of 2010-05-08 Cocoa Emacs 23.2 builds correctly on Snow Leopard (Mac OS X 10.6.x).

As of October 2011, the version of autoconf on OS X Lion is not recent enough to configure/compile Emacs from source. There is a workaround provided by using the autogen/copy_autogen script which will build emacs using pre-generated versions of the required build files. See the comments in `autogen/copy_autogen` for more information.


AquamacsEmacs can be built via build script or manually. The source is available from a Git repository. Then, do:

  make install

When the build is complete, find Aquamacs.app in .nextstep.

Note: changes to any source files in src/ require a simple “make”. The binary will directly be installed into nextstep/Aquamacs.app. Changes to source files in lisp/ require a “make install”. Changes to any lisp files directly in the .app bundle may or may not take effect (upon restarting Aquamacs): for many such files (list lisp/site-load.el), you must call “make”.

Detailed build instructions are available on BuildingAquamacs.

X11 Emacs

Directions to build and install may be found in the INSTALL or INSTALL.REPO files. The basic build and installation of the X11 Emacs application uses the commands:

    ./configure --with-x
    sudo make install

Carbon Emacs (for Emacs<23)

Directions to build and install may be found in the file newly downloaded to emacs/mac/INSTALL. The basic build and installation of the carbon Emacs application uses the commands:

    ./configure --enable-carbon-app
    sudo make install

Note: Carbon emacs has been replaced with Cocoa Emacs in Emacs 23.x. This is why the option --enable-carbon-app is no longer recognised by configure.

Installing Emacs with a Package Manager

Package managers provide a convenient way to install and maintain/upgrade software.


Fink http://fink.sourceforge.net/ includes various versions of Emacs in packages such as `emacs23`, `emacs24`, emacs24-nox`. It also includes packages for various Emacs extensions such as AUCTeX.


Homebrew has Emacs 25.3 as of October 2017.

Cask homebrew installation

Homebrew now recommends to use the cask version with the following message: “Please try the Cask for a better-supported Cocoa version”

To install the cask version:

brew cask install emacs

This installs a pre-built package from https://emacsformacosx.com/

Standard homebrew installation

If you prefer not to run the cask version, you can still use the old homebrew recipe.

Other options include:

To install using the --with-cocoa switch, one simply uses:

brew install --with-cocoa emacs

to get some “pretty” colours add the --srgb switch:

brew install --with-cocoa --srgb emacs

and finally link it to your Applications folder:

brew linkapps emacs

This creates a symlink and not an alias. So Spotlight may not find it (tested on macOS Sierra 10.12.2). Spotlight indexes symlinks to files that are treated as system files, but it doesn’t show them in the GUI. It does show aliases though, so you could just command-option-drag /usr/local/Cellar/emacs/*/Emacs.app to /Applications/ from Finder. Or:

$ osascript -e "tell application \"Finder\" to make alias file to (POSIX file \"/usr/local/Cellar/emacs-plus/25.3/Emacs.app\") at POSIX file \"$HOME/Applications\""

After installation, using the emacs command in the terminal or shell will run the -nw version of Emacs. If you want to run the Cocoa version using this command, you simply add a line to your .bash_profile.

Emacs-Plus version in tap

To instead use the emacs-plus version, which is like regular homebrew emacs but with some configuration options enabled,

brew tap d12frosted/emacs-plus
brew install emacs-plus

Mitsaharu version in tap

To instead use the Yamamoto Mitsuharu version of Emacs 25.2 (with more mac-specific features):

brew tap railwaycat/emacsmacport
brew install emacs-mac

and finally link it to your Applications folder:

brew linkapps emacs-mac


MacPorts http://www.macports.org/ is another means of installing Emacs on OS X (and other unix-alikes for that matter).

As of December 15, 2016 it provides the following packages:

See Available Ports for the current list.

The emacs executable installs to: /opt/local/bin/emacs

The emacs-app executable installs to: /Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs

The various emacs packages MacPorts offers (e.g., org-mode) will install to: /opt/local/share/emacs/site-lisp/

Note that Mac OS X Lion comes with GNU Emacs 22.1.1, located at: /usr/bin/emacs

Linux users, add these lines to your .profile (or .bashrc, etc.) to feel at home:

alias emacs='/Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs'

alias emacsclient='/Applications/MacPorts/Emacs.app/Contents/MacOS/bin/emacsclient'

For the OS X native (Cocoa) versions, once you’ve got MacPorts installed, run

   sudo port install emacs-app

or (if you prefer a – usually more recent– development version)

   sudo port install emacs-app-devel

It’s also possible to build the development version of GNU Emacs with ATSUI – Apple Type Services for Unicode Imaging.

Terminal Emulation

Read up on iTerm2 if you want to spend most of your time in ssh using emacs rather than the GUI.


Visit Mac files with native Mac app in dired

Use the shell mode. Make sure cursor is at the file, then type: ! open <RET>

Using the GUI Emacs.app from the command line.

To debug-init:

open /Applications/Emacs.app --args --debug-init

To --debug-init if you installed the Emacs.app from Macports:

open -a /Applications/MacPorts/Emacs.app --args --debug init

To open a file from a terminal. This can be used in combination with the sudo command.

open -a /Applications/Emacs.app <file-name> 

As above but for when Emacs.app has been installed via MacPorts.

open -a /Applications/MacPorts/Emacs.app <file-name> 

Call Emacs from other programs

Insert this into the .bash_profile file in your home directory:

export EDITOR="/Applications/Emacs.app/Contents/MacOS/Emacs"

Unlike “open -a”, this command will open a new window, and won’t terminate until you close the window (C-x C-c). So, the calling program will wait until you’ve finished editing, before it reads the file. For example, change control programs like git and svn will call emacs to edit your description of a change.

Using Emacs.app from the Dock

Create an app that runs a shell script that runs Emacs.app, like this: use Finder to navigate to /Applications and double-click Automator.app. Select the document type “Application” and click “Choose”. In the list on the left, select “Library”. In the next list, find “Run Shell Script” and drag it into the workflow area on the right. In the new shell script, delete the text and replace it with:

cd # Start in my home directory.
# Use my environment:
echo '/Applications/Emacs.app/Contents/MacOS/Emacs "$@"' | bash --login -s "$@"

Select “Shell: /bin/bash” and “Pass input: as arguments”. Click “File > Save…” and choose a name and location for your new app. For example, you might choose the /Applications directory and name the app “Emacs for Dock.” Don’t replace Emacs.app.

If you like, you can change your new app’s icon to match Emacs.app, like this: select Emacs.app and right-click “Get Info” or press cmd+i. In the info window, select the small icon in the top left corner and copy it (cmd+c). Next, select your new application, get its info, select the small icon and paste (cmd+v).

Drag your new app into the Dock as usual, and you’re good to go.

Your new app does two things that the Dock doesn’t (on Mac OS 10.9). The “cd” command causes emacs to start in your home directory, instead of the root directory “/”. The --login option gives emacs the same environment as an interactive Terminal. In particular, it gives emacs your usual PATH environment variable, so you can run commands in emacs the same as commands in Terminal. An alternative to --login is -i, which sets the environment differently, as described in the Bash reference manual.

If you followed above guide, and registered the app to the dock, and clicked it, it will actually create another icon in the dock for the running Emacs application. After that, if you click the original app icon, it will not create another running app in the Dock, but the Automator might spin infinitely, as you already have it (as in the second app icon).

If you’re using “M-x server-start”, then you could use following script instead above one:


cd # start in my home directory

if pgrep -U $(id -u) $(basename $EMACS) >/dev/null; then
  if [ "$#" -eq 0 ]; then
    # set -- -e '(select-frame-set-input-focus (car (or (visible-frame-list) (frame-list)))'
    echo "\"$EMACSCLIENT\" -e '(select-frame-set-input-focus (car (or (visible-frame-list) (frame-list))))'" | bash --login -s "$@";
    echo "\"$EMACSCLIENT\" -n \"\$@\"" | bash --login -s "$@";
  echo "\"$EMACS\" \"\$@\"" | bash --login -s "$@" &
  disown %-

Above script is tested in Aquamacs, but it may work with Emacs. What it does, if you click the original App Icon twice, it will just give the focus to the Emacs(Aquamacs), and if you drag a file to it, it will call emacsclient to transfer it to the Emacs process. If there is no Emacs process, it will create it. – CinSK

Use Alt/Option as Meta Key under terminal emulators

For Terminal.app, starting from Snow Leopard: Go to Preferences > Settings > Keyboard > Use option as meta key. Starting from El Capitan (or maybe earlier): Go to Preferences > Profiles > Keyboard > Use Option as Meta Key.

For iTerm: Go to Manage Profiles > Keyboard profiles > (your profile) > Option Key as… For iTerm2: Go to Preferences > Profiles > Keys > Left/Right option key acts as: Meta

If you want to use Option key for both international characters and Meta key in Emacs, see this page for iTerm 0.10.x patch and/or binary.

Alt-b and Alt-f for navigating by word also works for your shell now.

Use Left Command as Meta Key under iTerm2 terminal emulator

  1. In iTerm2 go to Preferences > Keys
  2. Under Remap Modifier Keys, change Left Command Key to behave like Right Option
  3. Then go to Preferences > Profiles > $YourProfile > Keys
  4. On the bottom right of the screen click “Right option key acts as: +Esc”

Call AppleScript from Emacs

I use Andrew Choi’s build of GNU Emacs at work every day on OS X. I keep some notes and some Lisp functions for calling AppleScript from Emacs in my advogato.org diary:


Encoding for Terminal.app on OS X

The OS X Terminal.app uses UTF-8 by default. To get the correct behaviour from the Emacs that comes with OS X, I use the following settings in my InitFile file:

    (set-terminal-coding-system 'utf-8)
    (set-keyboard-coding-system 'utf-8)
    (prefer-coding-system 'utf-8)

you also can write accents like this C-x 8 ‘ character see C-x 8 C-h

See UnicodeEncoding.

This also works with XEmacs 21.5.9 and above, at least.

In shell-mode, the [C-up] and [C-down] key-bindings do not work as expected to browse the history ring. The problem is that Terminal.app does not properly send these control sequences. To fix this behavior, open Terminal.app Preferences>>Settings>>Keyboard. Select the “+” button and you will see that you can add bindings to the “cursor down” key with the “control” modifier. Select “send string to shell”, and enter “ESCp”, i.e., emacs M-p. Similarly, define control cursor up to send “ESCn” to the shell.

Binding modifier keys

The variables available for binding the modifier keys:


values can be 'control, 'alt, 'meta, 'super, 'hyper, nil (setting to nil allows the OS to assign values)

Also see http://lists.gnu.org/archive/html/help-gnu-emacs/2011-02/msg00019.html

example usage:

;; key bindings
(when (eq system-type 'darwin) ;; mac specific settings
  (setq mac-option-modifier 'alt)
  (setq mac-command-modifier 'meta)
  (global-set-key [kp-delete] 'delete-char) ;; sets fn-delete to be right-delete

Example to bind the mac-right-option-modifier to 'none so you can still use it to write accents:

(when (eq system-type 'darwin)
  (setq mac-right-option-modifier 'none))

Emacs keybindings in Cocoa Apps

This information does not regard the actual use of emacs, but I think many people will be happy to find out that some cursor movement / text editing keybindings can be used in Cocoa Apps. If you ever happen to use any other application on your Mac … You can also set up additional keybindings as described in this document.

http://www.lorax.com/FreeStuff/TextExtras.html provides additional Emacs like features to every Cocoa application like alt-/ completion

Emacs keybindings in Terminal

So control-s is just beeping at me in emacs in the Mac OS X Terminal (10.4) on my home machine but works fine on 10.2 on my work machine – what gives? I’ve looked into the flow control tty issue and tried to disable it – still emacs just sits there beeping. M-x save-buffers and M-x isearch gets to be a pain. Any hints for the Mac OS X Terminal?

I don’t know the answer to this, but the fact that it is beeping means that Emacs is probably getting it and just not understanding it. If it had anything to do with flow control, you wouldn’t get even beeping. – JonathanArnold
this can be caused by checking the “speak selected text when the key is pressed” in the “Speech” control panel/sysprefs. The default key is ctrl-s. – JeremyLeipzig

Say I want to run the function “forward-sexp” bound to C-M-f. I should be able to get at it with “hold ctrl, hold alt, hit f”. However, if I actually do that I get the result of the command forward-word (M-f). To actually get forward-sexp I must “hit esc, hold ctrl, hit f”. However the alt key works fine as meta for things like M-x and basically anything that doesn’t also require ctrl. Anyone know how to fix this? (This is using Terminal.app on 10.4.9 btw).

iTerm sends C-M-keys and mouse events. Remote emacsen run for months via iTerm + ssh + screen. Any volunteers to hack C-M- and mouse input into Terminal.app with GDB and Objective-C?

See the following blog post for swapping the cmd and meta key. Also, if you want to retain one of the Option key functions as modifier for national characters, see this page for iTerm patch and/or binary.

Terminals on most operating systems (including Terminal.app) have a very limited set of keys that they send to applications. Rarely will they send C-M-keys to the app. For this and several other reasons I recommend running Emacs as a full app, not inside a terminal, except for quick changes. You can use Esc C-f in a pinch but it’s not as efficient as M-C-f.
C-M-f binding is processed properly in Leopard’s Terminal.app. I filed a bug-report with Apple when running Tiger and actually received an email reply telling me this would be fixed in Leopard (which it was).

Emacs Keybindings under X11

See the following blog post for using alt as your meta key:


Maximize Emacs 23.3 and 24+ in Mac OS X Lion

Fullscreen mode is not offered in either 23.3 or 24+. In trying to adapt the “maximize-frame” function below I inadvertently discovered that if one uses the maximize control button once the frame is maximized vertically, twice the frame is maximized both vertically and horizontally and three times results in the frame restored to its original size. Good enough for me!


You can also use Right Zoom ( http://www.macupdate.com/app/mac/30591/right-zoom ) with


Enable / Disable Anti-Aliasing

To turn on/off anti-aliasing, use the following commands. By default, anti-aliasing is on.

 (setq mac-allow-anti-aliasing t)    ;; turn on anti-aliasing (default)
 (setq mac-allow-anti-aliasing nil)  ;; turn off anti-aliasing

For Emacs >= 24.4 and OS X >= 10.5, the default font backend has changed, and no longer supports these commands. The old backend can be used instead by running the following command in Terminal.app.

 $ defaults write org.gnu.Emacs FontBackend ns

The commands will then work normally.

Another option is to use the following defaults command, which has some effect, but not as much as using the previous method.

 defaults write org.gnu.Emacs AppleAntiAliasingThreshold 100

To reverse the changes, use

 defaults delete org.gnu.Emacs AppleAntiAliasingThreshold

Open emacsclient in a new iTerm tab from Mac's Finder

-- -*- coding:utf-8 mode:applescript-*-
-- http://superuser.com/questions/457484/how-to-open-emacs-from-macs-finder
-- https://gist.github.com/ambethia/304964#comment-799519
--  use automator.app save this as an app
on run {input, parameters}
	tell application "iTerm"
		if (count of terminals) = 0 then
			set t to (make new terminal)
			set t to current terminal
		end if
		tell t
			set s to (make new session at the end of sessions)
			tell s
				exec command (("/usr/local/bin/emacsclient -t -nw \"" & POSIX path of first item of input as text) & "\"")
			end tell
		end tell
	end tell
end run

Hacking on the Sources

The section is meant to collect useful hacks to the C sources (or to Lisp sources that are executed before any init files are read, such as startup.el).

True fullscreen for the Cocoa build in Emacs 23

This fork has patches for true fullscreen and it works wonderfully.

$ git clone git://github.com/typester/emacs.git
$ cd emacs
$ ./configure --with-ns
$ make bootstrap
$ make install
$ mv nextstep/Emacs.app /Applications
(global-set-key (kbd "M-RET") 'ns-toggle-fullscreen)


Changing the Scrollbar Appearance

The size of the “knob” in a given window’s scrollbar is proportional to how much of the buffer is displayed in the window. When the whole buffer is displayed in the window, the knob takes up the entire scrollbar. I find this distracting (not to mention aesthetically objectionable), and much prefer the behavior of applications like iTerm that show an empty scrollbar slot in such cases.

You can get that effect in Emacs by making a small change to src/nsterm.m. Look for this bit of code:

- setPosition: (int)position portion: (int)portion whole: (int)whole
  NSTRACE (setPosition);

  em_position = position;
  em_portion = portion;
  em_whole = whole;

  if (portion >= whole)
    [self setFloatValue: 0.0 knobProportion: 1.0];
      float pos, por;
      portion = max ((float)whole*min_portion/pixel_height, portion);
      pos = (float)position / (whole - portion);
      por = (float)portion/whole;
      [self setFloatValue: pos knobProportion: por];
  return self;

and replace it with:

- setPosition: (int)position portion: (int)portion whole: (int)whole
  NSTRACE (setPosition);

  em_position = position;
  em_portion = portion;
  em_whole = whole;

  if (portion >= whole)
    [self setEnabled:NO];
      if (![self isEnabled])
          [self setEnabled:YES];
      float pos, por;
      portion = max ((float)whole*min_portion/pixel_height, portion);
      pos = (float)position / (whole - portion);
      por = (float)portion/whole;
      [self setFloatValue: pos knobProportion: por];
  return self;

A further change is to have the knob be of constant, minimal size, so that it only indicates position in the buffer, instead of changing size according to the portion of the buffer displayed in the window (I find the variable sizes distracting). To do this, use the replacement code:

- setPosition: (int)position portion: (int)portion whole: (int)whole
  NSTRACE (setPosition);

  em_position = position;
  em_portion = portion;
  em_whole = whole;

  if (portion >= whole)
    [self setEnabled:NO];
      if (![self isEnabled])
          [self setEnabled:YES];
      float pos;
      portion = max ((float)whole*min_portion/pixel_height, portion);
      pos = (float)position / (whole - portion);
      [self setFloatValue: pos knobProportion: 0];
  return self;

CategoryPorts CategoryBuilding