![[Home]](https://www.emacswiki.org/images/logo218x38.png)
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/.
Versions of macOS prior to 10.15 Catalina include a copy of GNU Emacs 22 without GUI support compiled in and thus Emacs is automatically available on all but the most recent versions of macOS via the terminal. On macOS 10.15 Catalina and higher, mg (previously known as microGNUemacs) is still included. However, there are other Emacs distributions geared towards macOS that include GUI support as well as other features that may make it a more appropriate choice for some, if not most people.
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. An X11 server available for Mac OS X is XQuartz. (Mac OS has no X11 server included by default; this has been the case since Mac OS X 10.8 Mountain Lion in 2012.)
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.
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).
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.
‘select’ that doesn’t require periodic polling, full screen support, subpixel font rendering, and smooth (pixel) scrolling. See the readme for more details. Available via Homebrew and MacPorts (as emacs-mac-app), as discussed below, or prebuilt binaries.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”.
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.
To build Emacs under Mac OS X:
./configure 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 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:
./configure make 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.
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
make
sudo make install
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
make
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.
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 28.2 as of Sep 2022.
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 install --cask emacs
This installs a pre-built package from https://emacsformacosx.com/
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:
ln -Fs $(find /usr/local -name "Emacs.app") /Applications/Emacs.app
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 defaults to opening Emacs.app in a new window, separate from the terminal. This represents a change in behaviour from the version of emacs pre-installed on macOS 10.14 and earlier. If you want to run emacs in the terminal then it must be invoked with the -nw “non-windowed” flag. You are required to configure environment variables (EDITOR and/or VISUAL), shell profiles (.bash_profile) and other configuration files (.git_config) to invoke emacs -nw if this is your desired default.
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
To instead use the Yamamoto Mitsuharu version of Emacs (27.1 as of 2020-11) (with more mac-specific features):
brew tap railwaycat/emacsmacport brew install emacs-mac
and finally link it to your Applications folder (default Homebrew App location):
ln -s /usr/local/opt/emacs-mac/Emacs.app /Applications
MacPorts http://www.macports.org/ is another means of installing Emacs on Mac OS X or macOS (and even other Unix-like systems for that matter which MacPorts also supports).
As of May 30, 2022 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.
To instead use the Yamamoto Mitsuharu version of Emacs (27.1 as of 2020-11) (with more mac-specific features):
sudo port install emacs-mac-app
The application will appear in your Applications/MacPorts folder.
pkgsrc http://pkgsrc.org/ is yet another means of installing Emacs on Mac OS X or macOS.
Prebuilt binaries are available from https://pkgsrc.joyent.com/install-on-osx/.
pkgin in emacs
Read up on iTerm2 if you want to spend most of your time in ssh using emacs rather than the GUI.
Use the shell mode. Make sure cursor is at the file, then type: ! open <RET>
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>
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.
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. [Beware if using zsh: the environment is that for a non-interactive login shell; that is [.]zshrc is *not*sourced; Mac OS 11.6]. 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:
EMACS=/Applications/Aquamacs.app/Contents/MacOS/Aquamacs EMACSCLIENT=/Applications/Aquamacs.app/Contents/MacOS/bin/emacsclient 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 "$@"; else echo "\"$EMACSCLIENT\" -n \"\$@\"" | bash --login -s "$@"; fi else echo "\"$EMACS\" \"\$@\"" | bash --login -s "$@" & disown %- fi
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
If you want the Automator gear to stop spinning, try replacing the two lines between the last else and fi with
nohup bash --login -c "$EMACS "$@"" >/dev/null 2>&1 &
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.
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:
http://advogato.org/person/wainstead/
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.
The variables available for binding the modifier keys:
mac-function-modifier mac-control-modifier mac-command-modifier mac-option-modifier mac-right-command-modifier mac-right-control-modifier mac-right-option-modifier
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))
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
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?
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).
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.
Recent macOS versions require you to separately give Emacs (and Terminal!) access to your disk.
GNU Emacs for OSX runs a Ruby wrapper, so you actually have to grant full disk access both to Emacs and to /usr/bin/ruby.
See the following blog post for using alt as your meta key:
http://tylerkieft.com/archives/2006/10/05/redefine-the-x11-meta-key-in-mac-os-x/
If you want to use the default shortcuts for copy, paste, cut etc. macOS, put this is your .init.el. Since M-x is overwritten in line 2, don’t forget to reassign it. See the last line as an example.
(global-set-key (kbd "M-c") 'kill-ring-save) ; ⌘-c = Copy (global-set-key (kbd "M-x") 'kill-region) ; ⌘-x = Cut (global-set-key (kbd "M-v") 'yank) ; ⌘-v = Paste (global-set-key (kbd "M-a") 'mark-whole-buffer) ; ⌘-a = Select all (global-set-key (kbd "M-z") 'undo) ; ⌘-z = Undo (global-set-key (kbd "≈") 'execute-extended-command) ; Replace ≈ with whatever your option-x produces
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!
-pmr
You can also use Right Zoom ( http://www.macupdate.com/app/mac/30591/right-zoom ) with
-dwd
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
-- -*- 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" activate if (count of terminals) = 0 then set t to (make new terminal) else 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
;; On Mac platform, Emacs can't enter Mac's native full-screen mode,
;; otherwise it will cause white screen and left and right sliding
;; after the original full-screen property is also integrated when
;; `make-frame' is created.
;;
;; So set `ns-use-native-fullscreen' and `ns-use-fullscreen-animation'
;; first to prevent Emacs from using Mac's native full-screen mode.
;; Instead of switching to the separate full-screen workspace of the
;; Mac, the traditional full-screen mode, traditional full-screen
;; mode, will only be in full screen in the current workspace.
;;
;; This way to execute `make-frame' when closing the code or plugin,
;; there will be no bugs caused by the sliding of the Mac's separate
;; workspace.
;;
;; On the Mac platform, you can't use `set-frame-parameter' and
;; `fullboth' directly to set the full screen. That would also cause
;; the Mac window manager to directly throw the Emacs window into a
;; separate workspace, thus producing the same bug for `make-frame'.
;;
;; Therefore, when starting, set Emacs to maximize the window state by
;; `set-frame-parameter' and `maximized', and then set it to full
;; screen state after 5 seconds.
;;
;; Mac will not move the Emacs window to a separate workspace, and
;; finally solve the problem that the native full-screen window on the
;; Mac platform causes the `make-frame' to slide left and right.
(setq ns-use-native-fullscreen nil)
(setq ns-use-fullscreen-animation nil)
(run-at-time "5sec" nil
(lambda ()
(let ((fullscreen (frame-parameter (selected-frame)
'fullscreen)))
;; If emacs has in fullscreen status, maximized
;; window first, drag from Mac's single space.
(when (memq fullscreen '(fullscreen fullboth))
(set-frame-parameter (selected-frame)
'fullscreen 'maximized))
;; Manipulating a frame without waiting for the
;; fullscreen animation to complete can cause a
;; crash, or other unexpected behavior, on macOS
;; (bug #28496).
(sleep-for 0.5)
;; Call `toggle-frame-fullscreen' to fullscreen emacs.
(toggle-frame-fullscreen))))
Don’t fullscreen frame when emacs starts, otherwise the macOS window manager will move emacs window to another single space, above code can make emacs just fullscreen frame in current space. —AndyStewart
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).
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)
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];
else
{
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];
else
{
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];
else
{
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;
}