Installation on macOS

This page explains how to install EXWM as the XQuartz window manager on macOS.

Note that EXWM cannot manage native macOS applications at all, only X11 applications will be managed.

The following instructions assume a bash shell.

1. Install XQuartz.

   Follow instructions at https://www.xquartz.org.

2. Install the X11 version of Emacs.

   Many Emacs packages for macOS do not come with X11 support. For example, the Homebrew package manager only distributes Emacs with Cocoa support. The following options are available for installing X11 Emacs on MacOS:

   From MacPorts

   The x11 variant of Emacs comes with X11 support using Lucid widgets and can be installed with the following command (after installing MacPorts):

   $ sudo port install emacs +x11

   Either the +gtk or +motif flags can be appended to the above command before running it to instead use the GTK or Motif toolkits, respectively.

   NOTE: Please, report whether other package managers (Fink, Nix ...) distribute the X11 version of Emacs.

   From source

   Using different versions of Emacs can lead to issues with byte-compiled code; make sure to check out the tag corresponding to other installed Emacs version, if any. In the instructions below, we assume Emacs 26 is already installed on the machine, therefore select the emacs-26.3 tag.

   Note as well that Xft fonts look blurry on Retina displays (see https://bugs.freedesktop.org/show_bug.cgi?id=92777 for details). This can be worked-around by avoiding the use of Xft fonts within Emacs. The instructions below check whether the system has a Retina display and compile Emacs without Xft support if that is the case.

   Difficulties finding Emacs with X11 support on macOS apply as well to Gtk with X11 support. In that case use the lucid backend (--with-x-toolkit=lucid in the installation script).

   At last, note that the documentation is not built and GIF support is disabled in the script below. Would you want to enable them, please delete the --without-makeinfo and --without-gif arguments.

   $ git clone --branch emacs-26.3 'git://git.sv.gnu.org/emacs.git' /opt/src/emacs-x11
   $ cd /opt/src/emacs-x11
   $ sh autogen.sh
   $ mkdir build
   $ cd build
   $ system_profiler SPDisplaysDataType | grep -q Retina && WITH_XFT='no' || WITH_XFT='yes'
   $ ../configure --prefix='/opt/emacs-x11' --without-ns --with-x --with-x-toolkit='lucid' --with-xft="$WITH_XFT" --without-makeinfo --with-gif='no' --enable-symbols PKG_CONFIG_PATH='/opt/X11/lib/pkgconfig/'

3. In order to substitute the default XQuartz window manager (named quartz-wm) with EXWM, a file named $HOME/.xinitrd.d/NN-xxx.sh must be created which launches our X11 Emacs as its last action. This will prevent quartz-wm from starting.

   $ mkdir "$HOME/.xinitrc.d"
   $ cat <<EOF >"$HOME/.xinitrc.d/99-exwm.sh"
   exec /opt/emacs-x11/bin/emacs --eval "(add-hook 'after-init-hook #'exwm-enable)"
   EOF
   $ chmod +x "$HOME/.xinitrc.d/99-exwm.sh"

   The --eval above makes sure EXWM is enabled when launching Emacs. Can be removed if EXWM is started from your configuration.

Optional configuration

Disable three button mouse emulation

By default, XQuartz activates option "Emulate three button mouse", which hijacks s-mouse-1 bindings (that is, left click while holding the Option key). This feature conflicts with EXWM's bindings for moving floating windows.

In order to disable this feature, open the XQuartz Preferences dialog by pressing the XQuartz button in the menubar and choose Preferences; then find the Input tab and disable the Emulate three button mouse option. Alternatively, run the following command:

defaults write org.macosforge.xquartz.X11 enable_fake_buttons 0

Character composition

By default, XQuartz maps both option keys to Mode_Switch (which composes characters), and knows nothing about Super. This behaviour can be changed by editing $HOME/.Xmodmap. The following example configures the left option to be interpreted as Super, and leaves the right option to its default of composing characters.

$ cat <<EOF >"$HOME/.Xmodmap"
keycode 66 = Super_L
clear mod1
add mod1 = Super_L
EOF

Disable startup program

XQuartz defaults to launching XTerm at startup. This behaviour can be disabled by issuing the following command:

defaults write org.macosforge.xquartz.X11 app_to_run /usr/bin/true

Visit the following link for more details: https://apple.stackexchange.com/questions/53734/how-do-i-prevent-x11-opening-an-xterm-when-it-starts.