This guide shows you how to run Emacs with the Windows Subsystem for Linux WSL in Windows 10. Emacs can either be run with a graphical display or directly in the terminal.
This guide is using Ubuntu 18.04 LTS as Linux distribution.
- Enable the Windows Subsystem for Linux
- Install the Linux distribution
- Use Windows Terminal
- Configure WSL
- Install Emacs
- Run Emacs in Terminal
- Run Emacs in Graphical Display
- Remarks
- FAQ
Open PowerShell as Administrator and run the following to enable the feature:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
Restart your computer (you should be prompted to do so).
This can also be done with:
- Open Control Panel
- Programs and Features
- Turn Windows Feature on or off
- Check Windows Subsystem for Linux
Install a Linux distribution. This guide should work for all Debian based ones. But it is only tested on Ubuntu 18.04.
You can install the Linux distribution:
- from the Microsoft store
- from the command line (used in this guide)
- manually (download)
Installing Ubuntu 18.04 from command line with PowerShell.
curl.exe -L -o ubuntu-1804.appx https://aka.ms/wsl-ubuntu-1804
Add-AppxPackage .\ubuntu-1804.appx
This step is optional but recommended.
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.
To make it open WSL by default:
- Open the Windows Terminal.
- Open the settings by clicking on the dropdown button in the tab bar and then select settings (bound to Ctrl-,).
- Copy the GUID for WSL (example: {12345678-1234-1234-1234-1234567890AB}).
- Set the default profile to the one copied from WSL:
{ ... "defaultProfile": "{12345678-1234-1234-1234-1234567890AB}", ...
To change the default path to ~:
- Go to the settings (Ctrl-,).
- Add a line in the WSL part at the end:
{ ... "source": "Windows.Terminal.Wsl", "startingDirectory": "//wsl$/Ubuntu-18.04/home/<username>/" },
Start the WSL (in Windows Terminal if you have installed it) and configure it.
Make sure everything is up to date:
sudo apt update
sudo apt upgradeWith Windows 10 Build 17093 and later certain functionality (automount options
and network configuration) in WSL can be configured inside the file
/etc/wsl.conf.
No need to touch that file, just leave the defaults.
Instead of using root user it’s better to add a user and use that as default user.
sudo adduser <username>Make that user be a sudo user:
sudo usermod -a -G sudo <username>Change the default user which is used when starting the WSL.
Open cmd.exe and run:
ubuntu config --default-user <username>Restart WSL.
You can change the default back to root by using root as username. To change
to root inside WSL temporarily use sudo su -.
Generate a new ED25519 SSH key pair:
ssh-keygen -t ed25519 -C "email@example.com"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.pubThis might be needed:
sudo update-locale LANG=en_US.UTF8You can mount network drives temporarily with:
# mount a mapped drive
sudo mkdir /mnt/g
sudo mount -t drvfs G: /mnt/g
# unmout
sudo umount /mnt/g
# mount network location
sudo mount -t drvfs '\\server\share' /mnt/shareAll mounted drives are found under /mnt:
cd /mnt
lsTo do so the fstab file needs to be configured.
For instance to mount H: add this to “/etc/fstab” (the directory has to exist to
make this work, so in this case sudo mkdir /mnt/h is needed beforehand):
H: /mnt/h drvfs defaults 0 0
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.
Install all dependencies for Emacs and then install Emacs 27.1:
## install dependencies (got those from all over the net and from the snap)
sudo apt install -y autoconf automake autotools-dev bsd-mailx build-essential \
diffstat gnutls-dev imagemagick libasound2-dev libc6-dev libdatrie-dev \
libdbus-1-dev libgconf2-dev libgif-dev libgnutls28-dev libgpm-dev libgtk2.0-dev \
libgtk-3-dev libice-dev libjpeg-dev liblockfile-dev liblqr-1-0 libm17n-dev \
libmagickwand-dev libncurses5-dev libncurses-dev libotf-dev libpng-dev \
librsvg2-dev libsm-dev libthai-dev libtiff5-dev libtiff-dev libtinfo-dev libtool \
libx11-dev libxext-dev libxi-dev libxml2-dev libxmu-dev libxmuu-dev libxpm-dev \
libxrandr-dev libxt-dev libxtst-dev libxv-dev quilt sharutils texinfo xaw3dg \
xaw3dg-dev xorg-dev xutils-dev zlib1g-dev libjansson-dev libxaw7-dev \
libselinux1-dev libmagick++-dev libacl1-dev gir1.2-javascriptcoregtk-4.0 \
gir1.2-webkit2-4.0 libenchant1c2a libglvnd-core-dev libicu-le-hb-dev \
libidn2-0-dev libjavascriptcoregtk-4.0-dev liboss4-salsa2 libsoup2.4-dev \
libsystemd-dev libwebkit2gtk-4.0-dev libx11-xcb-dev libxcb-dri2-0-dev \
libxcb-dri3-dev libxcb-glx0-dev libxcb-present-dev libxshmfence-dev \
x11proto-composite-dev x11proto-core-dev x11proto-damage-dev \
x11proto-fixes-dev
## download and install
cd ~
wget https://ftp.gnu.org/pub/gnu/emacs/emacs-27.1.tar.gz
tar -xzvf emacs-27.1.tar.gz
cd emacs-27.1
./configure
make
sudo make install
rm ~/emacs-27.1.tar.gzKeeps the directory where Emacs was cloned to in case any step fails (to clean or reinstall) or to be able to reconfigure.
There is also a script included in the repository with those steps.
Run Emacs with emacs -nw to see if it is working. You can also see what path
it is using as home with C-h v user-emacs-directory. That’s where you can place
your init.el etc.
To be able to run Emacs with a graphical display you need to install a Windows X server.
An X-server lets you access a Linux application or desktop environment’s graphic user interface (GUI).
You can use VcXsrv or Cygwin/X. Both are free and based on xorg.
Download VcXsrv from https://sourceforge.net/projects/vcxsrv/ and install it.
You have to install Cygwin and install additional packages:
- Download Cygwin from https://cygwin.com/install.html.
- Run the setup to install Cygwin. When you come to the
select packagesstep you have to add (change from skip to the newest version)xorg-serverandxinit. If you want to use the wizard (GUI) for launching the X-Server addxlaunchas well. - If you missed that step you can easily add those packages later on by running the setup again.
If you are using WSL2 some changes are needed. Make sure to also read the section at the end of this one.
Start XLaunch and use the defaults:
- Multiple Windows, Display number -1 (or 0 if not working), Next
- Start no client, Next
- Leave checkboxes, Next
- Finish
Make a shortcut (right click on your desktop > New > Shortcut) and use the following as target.
- With VcXsrv:
# Change the path if installed somewhere else. "C:\Program Files\VcXsrv\vcxsrv.exe" :0 -multiwindow -clipboard -wgl
- With Cygwin/X:
# Change the path if installed somewhere else. "C:\cygwin64\bin\run.exe" --quote /usr/bin/bash.exe -l -c "XWin :0 -listen tcp -multiwindow -clipboard -wgl"
You can put the shortcut into the startup folder to start it when booting. Or stick it to the task bar to launch it from there.
You can use the command from the Shortcut also from the command line.
Open WSL and run (this also changes the keyboard layout to US, remove if you don’t want this. Then it should use your default keyboard layout.):
export DISPLAY=:0.0
export LIBGL_ALWAYS_INDIRECT=1
# OPTIONAL Set the keyboard layout to US
setxkbmap -layout us
setsid emacs
exitThis will open Emacs in a new window. By using setsid this is done in a new
session and therefore the WSL can be closed after with exit. You can just change
it to emacs and remove exit if you want. Make sure x11-xkb-utils is
installed (sudo apt install x11-xkb-utils) if you want to change the keyboard layout.
To not have to type this over and over make an alias in ~/.bashrc or if you
installed zsh in ~/.zshrc:
alias eme='
export DISPLAY=:0.0
export LIBGL_ALWAYS_INDIRECT=1
setxkbmap -layout us
setsid emacs
exit
'Now you can fire WSL up and run eme.
You can create a shortcut on your desktop to launch Emacs. Create a new file
named emacs-wsl.vbs on your desktop with the following content (change bash
to zsh if you are using it):
Set oShell = CreateObject ("Wscript.Shell")
Dim strArgs
strArgs = "wsl bash -c 'export DISPLAY=:0.0 && export LIBGL_ALWAYS_INDIRECT=1 && setxkbmap -layout us && emacs'"
oShell.Run strArgs, 0, false
Now you can launch Emacs in WSL by double-clicking the file.
Was not able to test this so far but according to multiple sources this should work. Check out the open issue #3 for more.
To make this work on WSL2 you have to disable access control in VcXsrv by
changing the link to (added -ac flag):
# Change the path if installed somewhere else.
"C:\Program Files\VcXsrv\vcxsrv.exe" :0 -multiwindow -clipboard -wgl -acAnd to run Emacs you need to use this:
export DISPLAY_NUMBER="0.0"
export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):$DISPLAY_NUMBER
export LIBGL_ALWAYS_INDIRECT=1
# OPTIONAL Set the keyboard layout to US
setxkbmap -layout us
setsid emacs
exitDon’t touch your Linux files from Windows. Creating and changing Linux files from Windows can result in losing files or corrupting data.
This also means that if you want to for instance copy a file into your subsystem this has to be done from inside the WSL.
Looks like this is getting better if one has Windows 10 Version 1903 or newer:
It’s in %LOCALAPPDATA%\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\rootfs
See https://superuser.com/a/1280916.
To start WSL from Windows Explorer just type wsl into the location input box:
The drive has to be mounted else it will not work.
See https://docs.microsoft.com/en-us/windows/wsl/wsl-config#ways-to-run-wsl.