installing emacs on macOS

installing emacs on macOS

# emacs from homebrew package management

Last updated: CHkhmA

  1. Install only the command line tools (CLT) for macOS, not Xcode which is several GB. App Store tends to auto-update the tools afterwards.

    From Mojave:

    If you use your computer for programming, install the (free) Xcode Developer Tools by typing xcode-select --install in a terminal window, or by installing the whole Xcode package using the App Store. Then type sudo xcodebuild -license in a terminal window to accept the license.

    (Have yet to try those commands.)

  2. Use the installation command on the homebrew website:
    See its FAQ for the uninstall script, if re-installing.

    Packages must be removed from Caskroom before uninstalling brew, f.e.:

    > brew cask uninstall xquartz

    The uninstall script removed most everything in "/usr/local". Empty the remainder with:

    > sudo rm -rd each directory

    The uninstall script also removed:

  3. Optionally install XQuartz for ImageMagick's "display" program, and maybe for GIMP. XQuartz is a cask package, no compiling needed.

    > brew cask install xquartz
    > brew list
    > brew cask list
  4. Install ImageMagick before Emacs. "openjpeg" is the way to get JPEG 2000 (jp2).

    Last build time: 0dH

    > brew install --with-fontconfig --with-ghostscript --with-librsvg --with-openjpeg imagemagick
    > brew list
    cairo       ghostscript  jpeg      libtool      pkg-config
    fontconfig  glib         libcroco  little-cms2  xz
    freetype    graphite2    libffi    openjpeg
    fribidi     harfbuzz     libpng    pango
    gdk-pixbuf  icu4c        librsvg   pcre
    gettext     imagemagick  libtiff   pixman

    ImageMagick 7.x might be unreliable in emacs 25.x; consider imagemagick@6. The imagemagick@6 package is reported as "keg-only" and not linked in "/usr/local/bin/". Can create a new .bash_profile and add path to imagemagick@6 like so:

    > echo export PATH="/usr/local/opt/imagemagick@6/bin:$PATH" >> .bash_profile

    ImageMagick 7.x seems fine with emacs 26, and 27.0.50 so far.

  5. Install gnupg for use with ".authinfo" file.

    > brew install gnupg
  6. Install plain Emacs using "--with-cocoa" instead of the Mac-oriented version hosted at “”. Also ignore the recommended version in the cask.

    Include "--with-mailutils" for imaps support with rmail for email by using mailutils.

    Last build time: 0cK

    > brew install emacs --with-cocoa --with-ctags --with-librsvg --with-mailutils --with-modules
    > brew list
    cairo        glib         jpeg      libunistring  pixman
    emacs        gmp          libcroco  little-cms2   pkg-config
    fontconfig   gnutls       libffi    mailutils     readline
    freetype     graphite2    libpng    nettle        xz
    fribidi      gsasl        librsvg   openjpeg
    gdk-pixbuf   harfbuzz     libtasn1  p11-kit
    gettext      icu4c        libtiff   pango
    ghostscript  imagemagick  libtool   pcre

    CHji: emacs 26.1 failed to draw to the screen on macOS 10.14 Mojave. Workaround is to install via "--HEAD".

    Last build time: 0hZ

    > brew install emacs --with-cocoa --with-ctags --with-librsvg --with-mailutils --with-modules --HEAD
    > brew list
    autoconf    ghostscript  icu4c        libtiff       pango
    cairo       glib         imagemagick  libtool       pcre
    emacs       gmp          jpeg         libunistring  pixman
    fontconfig  gnu-sed      libcroco     little-cms2   pkg-config
    freetype    gnutls       libffi       mailutils     readline
    fribidi     graphite2    libpng       nettle        texinfo
    gdk-pixbuf  gsasl        librsvg      openjpeg      xz
    gettext     harfbuzz     libtasn1     p11-kit

Upgrading a --HEAD install is done with:

> brew reinstall emacs

Applications started in macOS obviously will miss out on shell environment variables. Start emacs from so the shell environment path will be gained by emacs, preferably in the background.

> emacs&

The emacs app will launch rather than as a text-only terminal because emacs is compiled with the option --with-cocoa. That terminal window can be used for other tasks when the emacs is started in the background.

Using emacs straight from the terminal (f.e. emacs -nw or built without "--with-cocoa") prevents viewing of images seemingly because the terminal is text only.

# additional tweaks

For tidiness's sake keep the emacs "init.el" file in "~/.emacs.d/".

If using an unmodified emacs, f.e. other than the Mac port:

# substitutions

A few functions have been overridden within copies of their corresponding lisp files. This maintains the original context with the original functions for easily comparing with a new version of emacs. Search for comments ";Override" and ";Emerged" to find the differences, or use = (command: ESC x dired-diff) within dired.

The original file can be found from the help documentation for one of its functions, t.i. Controlh f and one of the function names. Then follow the link in the help documentation to the file, invoke dired with ESC x dired (shortcut: Controlx d), and the suggested default directory will be for that file. Alternately, using ESC x dired-jump (shortcut: Controlx Controlj) in the view of a document will immediately show its directory within dired.

Rename the installed file with ".original" after its name (before the ".el.gz" extensions) at its location. In order to prevent accidental overwriting of the modifications, copy the substitute file to the location rather than linking it. Of course, compare differences after version upgrades before substituting again.

The original file was likely byte compiled (file of same name with ".elc" present), so byte compile the substitution file with Shiftb (command: ESC x dired-do-byte-compile) within dired mode.

# substitutions for dired mode and ls-lisp

A few differences for dired's use of ls-lisp are in this ls-lisp.el.gz file (emacs 25, 26, 27.0.50), notably: sexagesimal date/time for file listings (compatible with leap seconds); formatted number for file links.

Must also load it in the init file in order for it to be used by dired within restored buffers: (require'ls-lisp nil t). Requires the package in base.el.gz file for sexagesimal notation.


Sexagesimal notation for date/time. Only two characters needed for years 60–3599, and one character for anything else. Seven characters total, including seconds: yymdhms. No more 6 month rule.

ls-lisp-links-fmt (emerged)

Formatted text width for largest number of links for a file or directory in listing, therefore minimal width while also fitting when >999 links.

Another alternative includes additional use of base 60 for number of links and file sizes in this ls-lisp_2.el.gz file (emacs 27.0.50). Should replace file named "ls-lisp.el.gz". Has same changes and these additional differences:


Also converts number of links to base 60.


Undocumented function used by function ls-lisp-format. Converts file size to base 60, except with -h switch (for human readable, t.i. with units).

A third alternative includes conversion of drwxrwxrwx attributes to numeric values in this ls-lisp_3.el.gz file (emacs 27.0.50). For example, "-rw-r--r--" is equivalent to "-0644", and "drwxr-xr-t" is equivalent to "d1755". Should replace file named "ls-lisp.el.gz". Has same changes as previous two versions, and these additional differences:


Attribute string converted from drwxrwxrwx to d7777: entry type, numeric set-id, and then numeric perms for ugo. See manual for ls(1) in its \"The Long Format\" section, and manual for chmod(1) in its Modes section.

# substitutions for rmail mode

In emacs 27.0.50 the rmail library uses the variable rmail-remote-password for supporting the retrieval of email from only one email server (or many if they all use the same password), though it does support multiple file sources.

This rmail.el.gz file supports multiple email accounts from multiple email servers by using auth-source for credentials or prompts when unavailable (some prompts not yet tested).

In other words, add machine, port, login, and password for each email account into the .authinfo.gpg file. The login and machine (f.e. login@machine.domain.tld) for each account in rmail-primary-inbox-list will be matched to the info in the .authinfo.gpg file.

No new variables to set, no new functions to use; the variable rmail-remote-password will be ignored.

rmail-parse-url (;Override.)

Allows for optional account name. Ignores rmail-remote-password. Therefore, it supports multiple remote hosts in rmail-primary-inbox-list because it no longer attempts using same password for all remote hosts.

rmail-get-remote-account (;Emerged.)

Uses auth-source. Otherwise, prompts for account name for host.

rmail-get-remote-password (;Override.)

Uses auth-source. Otherwise, prompts informatively with "account@host" when querying for each remote host, rather than with merely the protocol. No longer saves any password in rmail-remote-password.

# substitutions for smtpmail

In emacs 27.0.50 the smtpmail library uses variables user-mail-address, smtpmail-smtp-user, smtpmail-smtp-server, smtpmail-smtp-service, and smtpmail-stream-type for supporting the use of only one email address.

This smtpmail.el.gz file supports multiple SMTP email accounts by using auth-source for credentials or prompts when unavailable (some prompts not yet tested).

In other words, add machine, port, login, and password for each email account into the .authinfo.gpg file. When sending a message, it automatically matches the email address in the "From:" field of the message and one of the typical port numbers for an SMTP machine (25, 465, or 587) with the credentials in the .authinfo.gpg file.

No new variables to set, no new functions to use. Those other variables are used only as fallbacks and should be considered deprecated.

smtpmail-try-auth-methods (;Override.)

Override for undocumented non-public function. Optional USER for account name, potentially deprecating smtpmail-smtp-user. Used by smtpmail-via-smtp.

smtpmail-via-smtp (;Override.)

Override for undocumented non-public function. Use "From:" field with auth-source for determining server and credentials. Fallback to user-mail-address, smtpmail-smtp-server, smtpmail-smtp-service, and smtpmail-stream-type, but all of these should be considered deprecated.

# emacs package manager

Installing packages in emacs is done with its package manager with ESC x list-packages.

Or a package can be installed from its buffer with ESC x package-install-from-buffer.

Or a package can be installed from its file if it's in the directory given by variable default-directory, such as it is when viewing the directory with ESC x dired, by using the command ESC x package-install-file.

The emacs package manager installs within the "~/.emacs.d/" directory, so they remain after uninstalling emacs with brew.

# other homebrew packages of interest


Apache webserver.

> brew tap homebrew/apache

Note emacs has its own packages (ESC x list-packages), one of which is named web-server (0.1.1).


Equivalent of pdfpages for pdfLaTeX.

> brew tap homebrew/tex

Note pdfjam depends on TeX, and TeX had a messy install no matter how it was done. Consider a GNU/Linux VM with TeX, if ever needed.


Commands for PDF files. See “man mutool”.

Consider ghostscript (“gs”), too.
Consider pdf-tools Emacs package for PDF files: brew tap homebrew/emacs.


Commands for plain text data files.


Decompress files of a particular zip type.


Provides unar and lsar for viewing rar files, f.e. in dired mode,


Works for zlib compressed files, f.e. ".ddm" in ".mm6". Also helpful with content streams in PDF files.


Is supposed to be able to convert ".docx" files.

Note TextEdit opens ".docx" files.

# brew maintenance

Confirm brew is stable:

> brew doctor

Update list of available packages:

> brew update

Upgrade packages:

> brew outdated
> brew upgrade

Uninstall example:

> brew uninstall emacs-mac
> brew cask uninstall xquartz

When upgrading apps, unlink the previous versions, then link:

> brew unlinkapps --dry-run
> brew unlinkapps
> brew linkapps

Also consider removing previous installations and downloads:

> brew cleanup -s

More in:
ls-lisp.el.gz (substitution)
ls-lisp_2.el.gz (substitution)
base.el.gz (sexagesmial notation system)
rmail.el.gz (substitution)
smtpmail.el.gz (substitution)
email in emacs
editing commands