Emacs-WSL

This guide shows you how to run Emacs with the Windows Subsystem for Linux WSL2 using Ubuntu as Linux distribution.

I’ve removed the detailed instructions on WSL 1 installation. For WSL 2, a link to the documentation is sufficient, as it’s straightforward to install. If you’re still using WSL 1, please refer to the older version of this documentation.

Contents

• Install Ubuntu
• Install Emacs 30
• Run Emacs in a Graphical Display
• Run Emacs in Terminal
• Optional Additions
• FAQ

Install Ubuntu

Go to Install WSL | Microsoft Learn and follow the instructions to install WSL 2 with Ubuntu.

Install Emacs 30

To install the latest Emacs 30 version in Ubuntu 22.04 follow those steps. For other Ubuntu Version some dependencies have other versions and need to be adapted:

1. Install all dependencies (mostly taken from the snap)
   

   sudo apt update
   sudo apt install -y autoconf automake autopoint bsd-mailx libtool build-essential \
     dbus-x11 debhelper dpkg-dev emacs-bin-common emacs-common g++-12 gawk \
     gcc-12 git gvfs ibus-gtk3 language-pack-en-base libacl1-dev libasound2 \
     libasound2-dev libaspell15 libasyncns0 libatk1.0-0 libatk-bridge2.0-0 \
     libatspi2.0-0 libbrotli1 libc6 libc6 libc6-dev libc6-dev libcairo2 \
     libcairo2-dev libcairo-gobject2 libcanberra0 libcanberra-gtk3-0 \
     libcanberra-gtk3-module libdatrie1 libdb5.3 libdbus-1-3 libdbus-1-dev \
     libdrm2 libegl1 libenchant-2-dev libepoxy0 libflac8 libfontconfig1 \
     libfontconfig1-dev libfreetype6 libfreetype6-dev libgbm1 libgccjit0 \
     libgccjit-12-dev libgcc-s1 libgdk-pixbuf2.0-0 libgif7 libgif-dev \
     libgl1 libglib2.0-0 libglvnd0 libglx0 libgmp10 libgnutls28-dev \
     libgnutls30 libgpm2 libgpm2 libgpm-dev libgraphite2-3 \
     libgstreamer1.0-0 libgstreamer-gl1.0-0 libgstreamer-plugins-base1.0-0 \
     libgtk-3-0 libgtk-3-dev libgudev-1.0-0 libharfbuzz0b libharfbuzz0b \
     libharfbuzz-icu0 libhyphen0 libibus-1.0-5 libice6 libicu70 libisl23 \
     libjbig0 libjpeg8-dev libjpeg-dev \
     libjpeg-turbo8 liblcms2-2 liblcms2-dev liblockfile1 liblockfile-dev \
     libltdl7 libm17n-0 libm17n-dev libmpc3 libmpfr6 libncurses5-dev \
     libnotify4 libnss-mdns libnss-myhostname libnss-sss libnss-systemd \
     libogg0 liborc-0.4-0 liboss4-salsa2 libotf1 libotf-dev libpango-1.0-0 \
     libpangocairo-1.0-0 libpangoft2-1.0-0 libpixman-1-0 libpng16-16 \
     libpng-dev libpulse0 librsvg2-2 librsvg2-dev libsasl2-2 libsecret-1-0 \
     libselinux1-dev libsm6 libsndfile1 libsoup2.4-1 libsqlite3-0 \
     libsqlite3-dev libssl3 libsss-nss-idmap0 libstdc++6 libsystemd-dev \
     libtdb1 libthai0 libtiff5 libtiff-dev libtinfo-dev libtree-sitter0 \
     libtree-sitter-dev libvorbis0a libvorbisenc2 libvorbisfile3 \
     libwayland-client0 libwayland-cursor0 libwayland-egl1 \
     libwayland-server0 libwebkit2gtk-4.0-dev libwebp7 libwebpdemux2 \
     libwebp-dev libwoff1 libx11-6 libx11-xcb1 libxau6 libxcb1 \
     libxcb-render0 libxcb-shm0 libxcomposite1 libxcursor1 libxdamage1 \
     libxdmcp6 libxext6 libxfixes3 libxfixes-dev libxi6 libxi-dev \
     libxinerama1 libxkbcommon0 libxml2 libxml2-dev libxpm4 libxpm-dev \
     libxrandr2 libxrender1 libxrender-dev libxslt1.1 libxt-dev libyajl2 \
     mailutils procps quilt sharutils texinfo zlib1g-dev libattr1 libblkid1 \
     libbsd0 libdevmapper1.02.1 libenchant-2-2 libexpat1 libffi8 libgd3 \
     libglib2.0-bin libhogweed6 libharfbuzz-dev
       

   There might be a dialog about the mail server configuration, just select no configuration.

2. Clone the latest Emacs 30 version into ~/emacs
   

   Change the directory if you want to clone it somewhere else.

   cd ~
   git clone --depth 1 --branch emacs-30 https://git.savannah.gnu.org/git/emacs.git
   # This might be slow over https, you can try this, but might be blocked
   # by a firewal:
   # git clone --depth 1 --branch emacs-30 git://git.sv.gnu.org/emacs.git
       

3. Configure and install Emacs
   

   This step will take some time, and you might be prompted to enter your password once.

   Optional packages used (feel free to remove any that you don’t need):

   • --with-tree-sitter Compile with tree-sitter. Is probably also the default, if tree-sitter is installed.

   Many packages like sqlite3 or modules are now (30.1) enabled by default. To get a list of available features use .configure --help.

   Other features you might want to enable:

   • --with-pgtk Use GTK to support window systems other than X. If you want to use Wayland instead of X11.

   cd ~/emacs
   export CC="gcc-12" CXX="gcc-12"
   ./autogen.sh
   ./configure --with-tree-sitter
   make -j$(nproc)
   sudo make -j$(nproc) install
       

   export CC="gcc-12" CXX="gcc-12" is added to make sure version 12 is used, else the default would be used and this might be an older version.

   Retain the directory where Emacs was cloned for reinstallation (if a step fails), reconfiguration or uninstallation.

   To check if Emacs is working, simply run it directly in the terminal using emacs -nw -q.

Update to a new Emacs version

If you want to change to update Emacs using the same branch as used when installing:

• Navigate to the installation folder.
• Pull the changes with git pull --depth=1
• Then run make -j$(nproc) and sudo make -j$(nproc) install.

If you want to change to another branch:

• Navigate to the installation folder (it is ~/emacs if you followed the instructions from here).
• Execute sudo make uninstall.
• Remove the folder.
• Start with the installation according to the manual again.

Use latest Snapshot

To use the latest snapshot you can clone the master branch:

git clone --depth 1 https://git.savannah.gnu.org/git/emacs.git

Run Emacs in a Graphical Display

WSL 2 now supports (Run Linux GUI apps with WSL | Microsoft Learn) running Linux GUI applications (X11 and Wayland).

To run Emacs in graphical display just open the Ubuntu terminal and run emacs. To make it detach the process from the controlling terminal use setsid emacs.

Run Emacs in Terminal

Run Emacs with emacs -nw in Ubuntu terminal.

Optional Additions

Use Windows Terminal

Install Windows Terminal from Microsoft from the Microsoft Store.

The Windows Terminal is a modern, fast, efficient, powerful, and productive terminal application for users of command-line tools and shells like Command Prompt, PowerShell, and WSL.

Change keyboard layout

This only works if you use X11. If using wayland just switch the window keyboard layout for the Emacs application window like you do for any other application in Windows.

If you want to change the keyboard layout used make sure x11-xkb-utils is installed (sudo apt install x11-xkb-utils) and add, for instance

setxkbmap -layout us

to ~/.bashrc or to an alias.

Generate SSH Key

Generate a new ED25519 SSH key pair:

ssh-keygen -t ed25519 -C "[email protected]"

A dialog will ask you to:

• input a file path: use the suggested path by pressing Enter
• enter a password: enter your password

To copy the generated ssh key into the clipboard use:

clip.exe < ~/.ssh/id_ed25519.pub

SSH-agent with ssh-ident

ssh-ident can be used as a simple way to utilize the SSH-agent.

ssh-ident starts the SSH agent for a specific identity on demand (once you actually need them) and sets a customizable lifetime for that identity. Another approach would be to launch the SSH agent during WSL startup. However, this prompts for a password every time, even if it’s not needed.

Install ssh-ident following the instructions provided in the documentation.

The following configuration is necessary to enable ssh-ident to work seamlessly with Magit:

;; Integrate with ssh-ident to ask for ssh password:
(add-to-list 'magit-process-password-prompt-regexps
             "^\\(Enter \\)?[Pp]assphrase for [^ ]*: ?$")
(add-to-list 'magit-process-password-prompt-regexps
             "^Bad passphrase, try again for [^ ]*: ?$")

Use en_US Language

Bash on Ubuntu on Windows starts on the language defined in your Country or Region settings (maybe this got changed, not sure). If you want to change the default language to en_US you may need to run the following commands:

sudo apt install -y language-pack-en language-pack-en-base manpages
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF8

Zsh and oh-my-zsh

If you want to use zsh and oh-my-zsh:

sudo apt install zsh
chsh -s $(which zsh)
sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

Restart WSL.

In some scripts you need to change bash to zsh to be able to use it when emulating a terminal in Emacs.

Shrink Title Bar If Using Wayland

Just use this css and save it as ~/.config/gtk-3.0/gtk.css.

FAQ

Where is the root folder located?

The root is accessible as \\wsl$ in file explorer.

How to access Linux files from Windows?

Run explorer.exe . in WSL to open the Windows File Explorer at the current location. The path will start with \\wsl$ unless it is a mounted drive. In the File Explorer the files and folders can be copied, moved and edited as usual (see this blog post).

How start WSL from File Explorer in the current folder?

To start WSL from Windows File Explorer just type wsl into the location input box or hold down Shift while right-clicking and select Open Linux shell here from the context menu. If it’s a network drive it has to be mounted else this will not work.