Emacs on Windows

I use the Windows installer from a nearby mirror of GNU.org as recommended on the Emacs website. Make sure to use runemacs.exe since it does not open an empty terminal before opening the Emacs GUI, unlike emacs.exe. It is a good idea to add runemacs.exe to your start menu and task bar to have it easily available. I have runemacs.exe as the leftmost icon in my task bar which means that I can launch it with Super-1.

You may also consider adding runemacs.exe as the default program to open .org, .md, .py, .js etc files. I find it easier to do so in File Explorer by right-cliking a file of that type and choosing Propteries… and setting the application to open that file type instead of using the Settings app which doesn't work by file type, but by program which always seems a bit backwards to me. The way I use Emacs, I tend to have a frame open at all times and visit files from inside Emacs, but when I use File Explorer, I often want files to open in other programs, usually because I want to show my students the files in the programs they use (Thonny, VSCode, Word, Excel, MySQL Workbench…) even if I usually would use the files of the same file types inside Emacs, so I have only set a few file types to open with runemacs.exe. Since I don't use emacsclientw.exe on Windows, I don't want to double click files in File Explorer or open them through the start menu since that opens a new Emacs frame if runemacs.exe is set to open those file types. I like to almost always work in just one Emacs frame.

I have stopped using Emacsclient on Windows since it doesn't work the same way as on GNU/Linux. It does not respect my settings for faces (fonts) or scroll bars from my config. If I open Emacsclientw on Windows directly, it complains that I haven't opened it with a file. On GNU/Linux, if I open Emacsclient without a file, it opens up with the scratch buffer. Since I want to have an Emacs frame open at all times and more frequently open files from inside Emacs than from the File Explorer, I quite often want to open emacsclientw without a file. Another weird thing is that when I kill the buffer with the file I opened emacsclientw with, Emacsclient quits. It doesn't do that on GNU/Linux. Since I want to keep the frame for further work through the day, this behaviour makes emacsclientw more or less unusable for me. The third annoyance is that if I forget to use M-x kill-emacs before restarting or turning off the Windows machine, it uses forever to turn off. Together, these annoyances were just too much, so I went back to open an Emacs frame after booting the machine and continue to use it until I turn the machine off.

Emacs needs external programs for some of its functionality. Below is a table that shows useful programs I use on Windows to get the functionality I need or want from Emacs. More details can be found in the relevant sections below.

Emacs looks for a .emacs.d directory or a .config/emacs/ directory or a .emacs file in $HOME. To set $HOME, press the Windows key, write environment and you should see the Edit Environment Variables program (Rediger systemmiljøvariabler if you use Norwegian Bokmål). Set the User variables for HOME to wherever you want it. I also found that it was useful for git to set LANG and LC_ALL since git and other programs compiled with MSYS2 respects the text encoding from those. I did this as part of my trial and error process to find ways around git's default conversion of text encoding and line endings, but I am not certain it is necessary after setting the system locale to UTF-8 and/or setting Git Bash's text encoding in the GUI (see the dealing with text-encoding section for more on this).

Windows uses UTF-16 under the hood, but on the surface it uses different text encodings depending on your locale. (GNU/Linux, BSD and MacOS use UTF-8 unless you configure them to use something else.) Windows uses CR and LF to end lines while GNU/Linux, BSD and MacOS X use LF. (Mac OS < 10 used CR.) There are different strategies to deal with this:

1. Use the locale's encoding on Windows and have git convert line endings on clone, pull and push.
2. Use UTF-8 and Unix line endings for every buffer and file inside Emacs, but configure Emacs to work with yanking (pasting) and killing (cutting) to and from the clipboard in Windows locale's text encoding. Tell git to not convert files and line endings.
3. Set Windows 11 to use UTF-8, set Emacs to use UTF-8 and Unix line endings and tell git to use UTF-8 and not convert line endings.

If you do 1, then you don't have to configure git, because that is its default behaviour on Windows. This supposes that you use your text editor(s) with Windows line endings, and possible also your locale's text encoding which makes writing a lot of glyphs, like emojis, Hangul, Hiragana etc, impossible. Even VSCode defaults to UTF-8 and Unix line endings, even on Windows. I think there is absolutely no advantages to this approach unless you never use any other platform than Windows.

If you do 2, then you have files with only UTF-8 and Unix line ending in your repos, but you have to configure Emacs to convert text when yanking and killing to/from the system clipboard. You also have to configure git not to convert CRLF to LF. (See the below section on how to do this.) Below is how you configure yanking and killing to work to and from iso-latin-1 which is the common text encoding for Windows in Northern Europe and North America. I tried this approach for a while, but would rather avoid another if-statement in my config if I could avoid it to keep things as similar as possible between Windows and GNU/Linux.

(if (eq system-type 'windows-nt)
   (set-clipboard-coding-system 'iso-latin-1)
  (set-clipboard-coding-system 'utf-8))

I used to use aspell with aspell-en and aspell-nb (or -no) depending on whether the distro ships both Nynorsk and Bokmål in the same package or have separate packages (nb = Norwegian Bokmål, nn = Norwegian Nynorsk, no = both Nynorsk and Bokmål). I did not find aspell-no or nb on chocolatey or msys2 and I had the same problem with the hunspell package available for Windows which comes with British and American English which I sometimes use, but not Norwegian Bokmål.

For a while, I turned off spelling on Windows, but I recently looked into it again and found that I could copy over the .dic and .aff files I get with LibreOffice since it uses hunspell as well. The LO installer installs Norwegian dictionaries with a "typical install" if you downloaded the installer by browsing to the download page with a Norwegian IP address. To use the dictionaries from LibreOffice, go to C:\Program Files\LibreOffice\share\extensions\dict-no\ and copy the files nb_NO.aff and nb_NO.dic. If you use another language, have a look in the extensions folders to find the folder with your relevant dictionaries. Go to the share\hunspell directory under where you installed hunspell. I use C:\Program Files\Hunspell\share\hunspell\ and paste the files there.

In addition I have taken the settings suggested by Getting spelling to work in Emacs on Windows and modified them slightly for my use. I now also use hunspell on GNU/Linux. I have also made a convenient function in my Emacs config to toggle between Norwegian Bokmål and British English, and bound it in my keymap to C-z i.

(use-package flyspell
  :hook ((prog-mode . flyspell-prog-mode)
         (text-mode . flyspell-mode))
  :init
  (when (eq system-type 'windows-nt)
    (setq ispell-program-name "C:/Program Files/Hunspell/bin/hunspell.exe"))
  (setq ispell-dictionary "nb_NO")
  (setq ispell-dictionary-alist
    '(("nb_NO" ":alpha" "[^[:alpha:]]" "[']" nil ("-d" "nb_NO") nil utf-8)))
  (setq hunspell-default-dict "nb_NO"))

On my GNU/Linux systems, I install a dictd server and some dictionaries so I don't need to be connected to the internet to use dictionary-lookup-definition. Since there is no dictd server package for Windows, I first tried to use dict.org to look up words. When I tried dictionary-lookup-definition, Emacs just froze. It did not use a lot of CPU, but it just did not respond do anything, including C-g. I had to kill it with the three-finger salute (Ctrl-Alt-Delete). Maybe the relevant ports are blocked by my network at work, so it might work for you even if it did not for me. Below, you see my configuration for dictionary mode. I check if I am on GNU/Linux and otherwise, don't load it since I cannot get it to work at work.

(use-package dictionary
   :if (eq system-type 'gnu/linux)
   :config
   (setq dictionary-server "localhost"))

Emacs can show .xlsx, .docx, .pptx, .odt, .odp and other MS365 (Formerly Microsoft Office) and LibreOffice (Open Document Format) files in doc-view-mode. It is very practical to go directly from dired to doc-view-mode in stead of waiting for LibreOffice or MS365 to start. To show these files it needs a python script called unoconv that comes with LibreOffice. You also need to set the path to that script to get it to work. Since newer versions of LibreOffice stalls when you open them on Windows 11, either if you launch Writer or use unoconv from Emacs, I had to install version 24.2.0.3 to get this to work properly. You find it with the Archive link on the LibreOffice download page.

I use pandoc with Emacs and also ox-pandoc to be able to export from Org mode to .docx format. Upper Secondary schools in Norway use MS365, so it is useful to be able to write .docx documents occasionally. I use LaTex a lot for export of PDFs from org files I have used with inter-present-mode in class. Both pandoc and LaTex can be installed with Chocolatey, but when using LaTex to export PDFs on Windows 11, I always got an error that wrapfig.sty was not installed. It probably doesn't come with the LaTex package from Chocolatey. The solution is to use MikTex instead. Install the package miktex.install with chocolatey. MikTex needs Perl to function, so you also need to install Strawberry Perl from its website to get the export functionality to work. As with any external programs, you also need to set the exec paths (see further down this blog post) to get the actual functionality, unlike on GNU/Linux where it just works.

Since I like to have as few windows open as possible since Windows ironically is terrible at handling windows (at least compared to the tiling window manager Sway which I use on GNU/Linux), it makes more sense to use PowerShell in shell mode and stay within Emacs instead of launching a new PowerShell window. (Some people think window snapping solves the inefficiencies of a floating window manager or desktop environment, but it doesn't since you have to do it manually with a keyboard shortcut or even more inefficiently by mousing around and dragging the windows to the edges. A tiling WM tiles automatically without any need to mouse around or press keyboard combos, which saves time and interruptions.)

By default, you get cmd.exe in Shell mode on Windows. I had some trouble finding good documentation of how to set it up with PowerShell. Some people suggest just setting PowerShell to explicit-shell-file-name, but that only partially worked since it gave me an error that PowerShell was invoked with a wrong argument. A lot of people pointed to someone on the Microsoft blogs that set up PowerShell in Shell mode, but in a way that removed the prompt. He had made an Elisp workaround to get the prompt back, but it seemed like there should be an easier way. The trouble is that comint mode, the mode shell mode is built on, sends -i by default to the shells it interacts with as an argument. I tried a couple of things and it turns out the solution is really simple.

(use-package shell
  :config
  (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
  (add-to-list 'comint-output-filter-functions 'ansi-color-process-output)
  (add-hook 'comint-output-filter-functions 'comint-osc-process-output)
  (add-hook 'shell-mode-hook (lambda() (company-mode 0)))
  (when (eq system-type 'windows-nt)
    (setq explicit-shell-file-name "C:/Windows/System32/WindowsPowerShell/v1.0/powershell.exe")
    (setq explicit-powershell.exe-args '("")))
  (when (eq system-type 'gnu/linux)
     (setq explicit-shell-file-name "/bin/bash")
     (setq system-uses-terminfo t)
     (setq comint-terminfo-terminal "xterm")))

In the code block above, if on Windows, I tell Emacs to run PowerShell and give it the arguments "" (ie, nothing) which remove the default -i argument, but adds nothing else. And now I have PowerShell in Shell mode. The rest of the configuration turns off company since the shells have their own tab-completion and turns on ansi-colours which both Bash and PowerShell can work with. If you prefer to use PowerShell 7 instead, use the path to it instead of the path to the built-in Windows PowerShell.

LSP is a standard Microsoft made for adding language support to VSCode that is now also used by other editors like NeoVim and Emacs. In Emacs, you just have to have the LSP servers you want installed, the correct paths configured and eglot, company and eldoc, if turned on, makes use of them in the mode for the associated programming or markup language. I tend not to like documentation constantly popping up with eldoc-mode, but use completions and warnings from eglot and company. Below is a table of the LSP servers I use and how to install them on Windows.

The Microsoft LSP servers give you the same completions, documentation and warnings as in VSCode. I would recommend against Microsoft's pyright which has given both me and my students errors that were not actual errors. For instance, it told me that I could not change data type for an element inside a list even if that is precisely what a dynamically typed language like python lets me do. I used the list internally in a function, so it was not like I was mutating a list I might use somewhere else in the file. Python-lsp-server, also called pylsp has never given me any errors that weren't actual errors. You may find more LSP servers at https://langserver.org/.

In addition, you have to turn eglot on in the relevant modes. I turn it on for all programming modes.

(use-package eglot
  :hook (prog-mode . eglot-ensure))  

Python mode in Emacs on GNU/Linux works out of the box with no setup if you have Python installed on your system. However, on Windows, Python mode does not work even if Python is installed. It does not help to add the directory Python is in to the exec-path or add it to the $PATH environment variable either. After trying those two things, I looked for a useful variable to set the path to the python executable and tried a couple of promising ones before finding the correct solution. In the code below, I set the docstring-style to Django which I prefer over the default pep-257 and then check if on Windows and if so, set the path to the shell to where I have python installed.

(setq python-fill-docstring-style 'django)
(when (eq system-type 'windows-nt)
  (setq python-shell-interpreter "c:/Python313/python.exe"))

After realising that using a key only available in the Emacs GUI, but not when using Emacs in a TTY or a graphical terminal, was dumb, I changed my prefix key for my keymap to C-z and no longer rebind CapsLock to <apps/menu> on Windows with PowerToys and <menu> in my Sway config on GNU/Linux. I use Lenovo ThinkPads and keyboards at home, so I had to switch Fn and Ctrl on my HP work laptop with its BIOS to not confuse my muscle memory when at work. If you need to rebind keys on Windows, and cannot do it in the BIOS of your computer, try PowerToys. You can get it in The Microsoft Store.

For Emacs to integrate with external packages on Windows, the exec path needs to include the file path to those packages. Below is my extra configuration for adding exec-paths in Windows. You may have placed the programs you have installed manually, like Hunspell, in other places, so adjust accordingly. You may also do this with customize, but I want to have it as part of my config since sometimes I let the custom-vars file where I keep the changes from customize drift a little bit away from the upstream emacs_config repo on some machines.

(when (eq system-type 'windows-nt)
  (custom-set-variables
 '(exec-path
   '("C:/Program Files/MiKTeX" "C:/Program Files/ImageMagick-7.1.2-Q16-HDRI" "C:/Python313/"
     "C:/ProgramData/chocolatey/lib/findutils/tools/install/bin/" "C:/WINDOWS/system32"
     "C:/WINDOWS" "C:/WINDOWS/System32/Wbem" "C:/WINDOWS/System32/WindowsPowerShell/v1.0/"
     "C:/WINDOWS/System32/OpenSSH/" "C:/Program Files/dotnet/" "C:/Program Files/Git/cmd"
     "C:/Program Files/nodejs/" "C:/ProgramData/chocolatey/bin" "C:/ProgramData/chocolatey/lib/mpv/"
     "C:/ProgramData/chocolatey/lib/mupdf" "C:/Users/AFK01217/AppData/Local/Microsoft/WindowsApps"
     "C:/texlive/2025/bin/windows" "C:/Users/AFK01217/AppData/Local/Programs/Microsoft VS Code/bin"
     "C:/Users/AFK01217/AppData/Roaming/npm" "C:/Users/AFK01217/AppData/Local/Pandoc/" "."
     "C:/Program Files/Hunspell/bin" "c:/Strawberry/perl/bin/" "C:/Program Files/LibreOffice/program"))
 '(image-load-path
   '("c:/Program Files/Emacs/emacs-30.1/share/emacs/30.1/etc/images/" data-directory load-path "c:/python313/")))
)