GNU Emacs FAQ for MS Windows

This is the FAQ for using GNU Emacs on MS Windows, as distributed with Emacs 29.1.90.

This FAQ is maintained by the developers and users of Emacs on MS Windows. If you find any errors, or have any suggestions, please send them to the help-emacs-windows mailing list.

At time of writing, the latest version of GNU Emacs is version 29.1.90.

Copyright © 2008, 2010–2024 Free Software Foundation, Inc.

This list of frequently asked questions about GNU Emacs on MS Windows with answers (“FAQ”) may be translated into other languages, transformed into other formats (e.g., Texinfo, Info, WWW), and updated with new information.

The same conditions apply to any derivative of the FAQ as apply to the FAQ itself. Every copy of the FAQ must include this notice or an approved translation, information on who is currently maintaining the FAQ and how to contact them (including their e-mail address), and information on where the latest version of the FAQ is archived (including FTP information).

The FAQ may be copied and redistributed under these conditions, except that the FAQ may not be embedded in a larger literary work unless that work itself allows free copying and redistribution.

Table of Contents

1 Introduction

This FAQ covers questions that are specific to running GNU Emacs on Windows. For more general information, see the other Emacs manuals. See Further information.

1.1 Why support GNU Emacs on Windows?

It is not our goal to “help Windows users” by making text editing on Windows more convenient. We aim to replace proprietary software, not to enhance it. So why support GNU Emacs on Windows?

We hope that the experience of using GNU Emacs on Windows will give programmers a taste of freedom, and that this will later inspire them to move to a free operating system such as GNU/Linux. That is the main valid reason to support free applications on nonfree operating systems.

1.2 Which versions of Windows are supported?

Emacs 29.1.90 is known to run on all versions of Windows 9X from Windows 98 onward, and all versions of the NT family starting from NT 4.0; this includes all the modern versions from Windows XP and on. The Windows port is built using the Win32 API and supports most features of the X version, including variable width fonts, images and tooltips. Emacs on Windows can be compiled as either a 64-bit or a 32-bit executable.

1.3 What other versions of Emacs run on Windows?

See Cygwin.

Emacs can also be compiled for MSDOS. When run on recent MS Windows, it supports long file names, and uses the Windows clipboard. See the msdos directory in the Emacs sources for building instructions (requires DJGPP).

2 Getting Emacs

2.1 Where can I download Emacs?

You can download Emacs releases from mirrors. They are distributed as compressed tar files, digitally signed by the maintainer who made the release.

Pre-compiled binaries for MS Windows may be made available on a best-effort basis in the windows subdirectory of the above ftp site (as zip files digitally signed by the person who built them). See the README file in that directory for more information. Building Emacs from source yourself should be straightforward, following the instructions in the nt directory, so we encourage you to give it a try. See How can I compile Emacs myself?.

The development version of Emacs is available from Savannah, the GNU development site.

2.2 How can I compile Emacs myself?

To compile Emacs on a 64-bit version of Windows 7 or newer, we recommend to use the MinGW-w64 port of GCC and Binutils with the MSYS2 suite of tools. For the details, see the file nt/INSTALL.W64 in the Emacs source distribution.

If you need to build or run Emacs on MS Windows before Windows 7, you have to use the MinGW port of GCC and the MSYS suite of tools. The file nt/INSTALL in Emacs source distribution contains the details.

Support for displaying images, as well as XML/HTML rendering and TLS networking requires external libraries, the headers and import libraries for which will need to be installed where your compiler can find them. Again, the details, including URLs of sites where you can download these libraries are in nt/INSTALL.W64 or nt/INSTALL. See Other useful ports, for auxiliary tools you may wish to install and use in conjunction with Emacs.

After unpacking the source, or checking out of the repository, be sure to read the instructions in nt/README and the respective install file.

2.3 How do I use a debugger on Emacs?

By default, Emacs is compiled with debugging on, and optimizations enabled. The optimizations may interfere with some types of debugging; the debugger may not show clearly where it is, or may not be able to inspect certain variables. If this is the case, reconfigure with CFLAGS='-O0 -g3'

The file etc/DEBUG contains general debugging hints, as well as specific notes about debugging Emacs.

GDB is the GNU debugger, which can be used to debug Emacs when it has been compiled with GCC. The best results will be obtained if you start gdb from the src directory as gdb ./emacs.exe. This will load the init file .gdbinit1 in that directory, to define some extra commands for working with lisp while debugging, and set up breakpoints to catch abnormal aborts.

A Windows port of GDB is installed with MinGW64-w64 and MSYS2 (‘mingw-w64-<arch>-toolchain’ group) or can be found on MinGW download sites and on some others.

3 Installing Emacs

3.1 How do I unpack the distributions?

The binary distributions are distributed as zip files, which are handled natively by Windows XP and later. For earlier versions, there are many tools that can handle the zip format, from InfoZip’s command line unzip tool, to 7zip’s multi-format graphical archive explorer. (Although popular, WinZip has caused problems with line-ends in the past, and is not Free software, so we do not recommend it.)

Source distributions are distributed as .tar.gz or .tar.xz files. 7zip and similar multi-format graphical tools can handle these, or you can get Windows ports of the command line gzip and tar tools from multiple sources, or use bsdtar. See Other useful ports.

The command to unpack a source distribution from the command line is:

tar xzf emacs-29.1.90.tar.gz

If this does not work with the versions of tar and gzip that you have, you may need to try a two step process:

gzip -dc emacs-29.1.90.tar.gz | tar xf -

You may see many messages from tar complaining about being unable to change the modification time on directories, and from gzip complaining about a broken pipe. These messages are usually harmless, caused by incomplete ports that are not fully aware of the limitations of Windows.

And here’s an example of using bsdtar (from the ‘libarchive’ package) to unpack a .tar.xz archive:

bsdtar -xf emacs-29.1.90.tar.xz

Expect bsdtar to unpack the whole distribution without any complaints.

Once you unpack the source distribution, look in the nt directory for build instructions.

3.2 How do I install Emacs after unpacking the binary zip?

You can run Emacs without any extra steps, but if you want icons in your Start Menu, or for Emacs to detect the image libraries that are already installed on your system as part of GTK+, then you should run the program addpm.exe, which is usually installed into the same bin directory with emacs.exe.

3.3 How do I get image support?

Emacs has built in support for XBM and PBM/PGM/PPM images. This is sufficient to see the monochrome splash screen and tool-bar icons. Since v22.2, the official precompiled binaries for Windows have bundled libXpm, which is required to display the color versions of those images.

Emacs is compiled to recognize JPEG, PNG, GIF, TIFF, and RSVG images also, but displaying these image types require external DLLs which are not bundled with Emacs. See Other useful ports.

3.4 What is my init file?

When Emacs starts up, it attempts to load and execute the contents of a file commonly called .emacs (though it may have other names, see Where do I put my init file?) which contains any customizations you have made. You can manually add lisp code to your .emacs, or you can use the Customization interface accessible from the Options menu. If the file does not exist, Emacs will start with the default settings.

3.5 Where do I put my init file?

On Windows, the .emacs file may be called _emacs for backward compatibility with DOS and FAT filesystems where filenames could not start with a dot. Some users prefer to continue using such a name due to historical problems various Windows tools had in the past with file names that begin with a dot. The init file may also be called .emacs.d/init.el. Many of the other files that are created by Lisp packages are stored in the .emacs.d directory too, which keeps all your Emacs related files in one place.

All the files mentioned above should go in your HOME directory. The HOME directory is determined by following the steps below:

  1. If the environment variable HOME is set, use the directory it indicates.
  2. If the registry entry HKCU\SOFTWARE\GNU\Emacs\HOME is set, use the directory it indicates.
  3. If the registry entry HKLM\SOFTWARE\GNU\Emacs\HOME is set, use the directory it indicates. Not recommended, as it results in users sharing the same HOME directory.
  4. If C:\.emacs exists, then use C:/. This is for backward compatibility, as previous versions defaulted to C:/ if HOME was not set.
  5. Use the user’s AppData directory, usually a directory called AppData under the user’s profile directory, the location of which varies according to Windows version and whether the computer is part of a domain.

Within Emacs, ~ at the beginning of a file name is expanded to your HOME directory, so you can always find your .emacs file by typing the command C-x C-f ~/.emacs.

3.6 Troubleshooting init file problems

If you’ve set HOME to a directory using one of the above methods, and Emacs still doesn’t load your init file, the first thing you should do is check to see what Emacs thinks HOME is set to. You can do this by evaluating the following expression in the *scratch* buffer using C-x C-e:

(getenv "HOME")

Look carefully at what is printed in the echo area, and make sure the value is valid. For example, if the value has trailing whitespace, Emacs won’t be able to find the directory. Also, be sure that the value isn’t a relative drive letter (e.g., d: without a backslash or a forward slash after the colon); if it is, then HOME is going to be whatever the current directory on that drive is, which is likely not what you want to happen.

3.7 How do I associate files with Emacs?

The recommended way to associate files is to associate them with emacsclientw.exe. In order for this to work when Emacs is not yet started, you will also need to set the environment variable ALTERNATE_EDITOR to runemacs.exe. To open files in a running instance of Emacs, you will need to add the following to your init file:


3.7.1 For use with Internet Explorer

You can use Emacs as the editor for composing mail for ‘mailto:’ links, reading Usenet for ‘news:’ links, and viewing source. The following registry entries control this:

Concept Index

Jump to:   -   .   2   8   _  
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Z  
Index Entry  Section

-nw, window size: Console window size

.emacs: Init file
.emacs.d: Location of init file
.mailcap: Attachments with Gnus

2 button mouse: Mouse trouble

8.3 filenames, problems caused: Does not run

_emacs: Location of init file

addpm: Installing binaries
addpm, using GTK+ image libraries: GTK
alt key, using windows keys as additional: Swap CapsLock and Control
ALTERNATE_EDITOR: Associate files with Emacs
ange-ftp: Using FTP
anti-virus software reporting a virus in Emacs: Virus
anti-virus software, bad interaction with: Anti-virus
anti-virus software, bad interaction with: Shell commands do nothing
arch, version control integration with Emacs: Version control
aspell: Spell check
associating files with Emacs: Associate files with Emacs
attachments, in gnus: Attachments with Gnus
auto protect, anti-virus option causing problems: Anti-virus
auto protect, anti-virus option causing problems: Shell commands do nothing

bash, using cygwin shell within Emacs: Bash
beep, changing the sound: Beep sound
binary files, determining by filesystem: Line ends by file system
black and white images, getting color images in Emacs: Image support
bold fonts, synthesized: Bold and italic
Borland C++, integration with Emacs: Borland C++ Builder
bugs in Emacs, how to debug: Debugging
bzr, version control integration with Emacs: Version control

C-c to copy: CUA
C-v to paste: CUA
C-x to cut: CUA
caps-lock, swapping with control key: Swap CapsLock and Control
checking that HOME is set correctly: Troubleshooting init file
clean Emacs registry settings: Uninstall
clipboard encoding: Garbled clipboard
clipboard, corruption of: Garbled clipboard
clipboard, NUL characters: Cut and paste NUL
color images, installing support for images in Emacs: Image support
compile, setting default command: Default compile command
compiling Emacs: Compiling
completion, using forward slashes in shell buffers: Shell completion forward slash
COMSPEC, effect on subprocesses of subprocesses: Incorrect DOS version
console, window size: Console window size
control key, swapping with caps-lock: Swap CapsLock and Control
copy with C-c: CUA
CUA key bindings: CUA
cut with C-x: CUA
cvs hanging when login needed: Subprocess buffering
cvs, version control integration with Emacs: Version control
cygwin bash as shell within Emacs: Bash
cygwin environment: Cygwin
cygwin mount points, using within Emacs: Cygwin paths
cygwin paths, using within Emacs: Cygwin paths
cygwin symlinks in dired: Dired ls
cygwin, library conflicts: Cygwin
cygwin, quoting arguments: Quoting issues

debugging Emacs: Debugging
debugging Emacs with GDB: Debugging
debugging init problems: Troubleshooting init file
delete Emacs directory: Uninstall
delete-selection-mode: Highlight selection
Desktop, finding where it is: Find-file and the Desktop
DevStudio, keeping source in sync: Reverting buffers
DevStudio, load in Emacs command: Edit MSVC
DevStudio, using Emacs as editor in: DevStudio
dired, interpreting symlinks the same way as cygwin: Dired ls
dired, using an external ls program: Dired ls
DOS line ends: Line ends
DOS port: Other versions of Emacs

echo, suppressing for shell input: Shell echo
Emacs debugging: Debugging
Emacs Development: Downloading
Emacs distribution, checking digital signatures: Encryption
Emacs source code: Downloading
emacsclient, associating files with: Associate files with Emacs
emacsclient, calling from Visual Studio: Edit MSVC
encoding, clipboard: Garbled clipboard
encryption: Encryption
EOF, sending to subprocesses: Subprocess EOF
exchange mouse-2 and mouse-3 buttons: Mouse trouble
Explorer, associating Emacs with files in: Associate files with Emacs
extracting Emacs distribution: Unpacking
ezwinports: EZWinPorts

failure to run, Emacs: Does not run
faqs, general: More information
faqs, old: More information
file associations: Associate files with Emacs
find, the POSIX command: Recursive grep
find, using with grep: Recursive grep
finding the Desktop: Find-file and the Desktop
findstr: Grep
findstr, recursive: Recursive grep
firewall, bad interaction with: Anti-virus
firewall, bad interaction with: Shell commands do nothing
floppy drive, access when subprocesses started: Subprocesses and floppy drive
flyspell: Spell check
font dialog, using a menu instead: Font menu
font dialog, using to find font names: Font names
font menu, adding fonts: Add fonts to menu
font XLFD name format: Font names
fontconfig font names in Emacs 23: Font names
fonts, displaying a menu: Font menu
fonts, localized font names: Localized fonts
fonts, where to find: International fonts
fontsets, defining: Non-latin display
fontsets, displaying a menu: Font menu
forward slashes for completion in shell buffers: Shell completion forward slash
ftp, client hanging: Subprocess hang
ftp, using within Emacs: Using FTP
full-screen console programs, as subprocesses: Subprocess hang

garbage on the clipboard: Garbled clipboard
getting Emacs: Downloading
gif, installing image support in Emacs: Image support
git, version control integration with Emacs: Version control
GNU intlfonts, for displaying all languages: Language display
GNU intlfonts, where to get: International fonts
gnus, attachments: Attachments with Gnus
gnus, mail and news client: Incoming mail with Gnus
gnuwin32 tools: GnuWin32
gpg, Windows binaries: Encryption
grep: Grep
grep, recursive through subdirectories: Recursive grep
GTK+ image libraries: GTK

HELLO file, displaying all: Language display
help, mailing lists: Mailing lists
help, manuals and other sources: More information
hg, version control integration with Emacs: Version control
highlighting the selected region: Highlight selection
HOME directory: Location of init file

image libraries, development: GnuWin32
image libraries, gnuwin32: GnuWin32
image libraries, GTK+: GTK
images, installing libraries for: Image support
imap, using Gnus: Incoming mail with Gnus
init file: Init file
init.el: Location of init file
installing Emacs: Installing binaries
interactive shell, using: Using shell
Internet Explorer, view source in Emacs: Using with Explorer
interoperability with cygwin: Cygwin
intlfonts, for displaying all languages: Language display
intlfonts, where to get: International fonts
ispell: Spell check
italic fonts: Bold and italic

jpeg, installing image support in Emacs: Image support

key layout, customizing: Swap CapsLock and Control
killing subprocesses, Windows 95/98/ME: Killing subprocesses

language support, finding fonts: International fonts
language support, fonts: Language display
language support, forcing Emacs to use specific fonts: Non-latin display
language support, third party programs on Windows 9x/ME: Third-party multibyte
latest development version of Emacs: Downloading
library conflicts with cygwin: Cygwin
line ends, automatic detection: Automatic line ends
line ends, determining by filesystem: Line ends by file system
locating files on the Desktop: Find-file and the Desktop

Mac line ends: Line ends
mail, attachments in gnus: Attachments with Gnus
mail, incoming with Gnus: Incoming mail with Gnus
mail, incoming with rmail: Incoming mail with Rmail
mail, other options: Incoming mail other
mail, outgoing: Outgoing mail
MAILHOST: Incoming mail with Rmail
mailing lists: Mailing lists
mailto URLs, associating with Emacs: Using with Explorer
man pages: Read man pages
manuals: More information
marked region, highlighting: Highlight selection
maximize frames from lisp: Window operations
mercurial, version control integration with Emacs: Version control
mh-e, mail client: Incoming mail other
middle button, on wheel mouse: Mouse wheel
middle mouse button, simulating: Mouse trouble
MIME, configuration for Gnus: Attachments with Gnus
mingw tools: MinGW
mingw-w64 tools: MinGW-w64
minimize frames from lisp: Window operations
monochrome images, getting color images in Emacs: Image support
monotone, version control integration with Emacs: Version control
mount points, cygwin: Cygwin paths
mouse buttons, problems with: Mouse trouble
mouse over to focus: Focus follows mouse
mouse wheel: Mouse wheel
movemail, using pop3: Incoming mail with Rmail
MSVC++, compiling within Emacs: MSVC command line
MSVC++, environment variables: VC++ environment
MSVC++, keeping source in sync: Reverting buffers
MSVC++, load in Emacs command: Edit MSVC
MSVC++, using Emacs as editor with: DevStudio
msys environment: MinGW
msys2 environment: MinGW-w64
MULE, finding fonts: International fonts
MULE, fonts: Multilingual fonts
MULE, fontsets: Non-latin display
multilingual display, finding fonts: International fonts
multilingual display, fonts: Multilingual fonts
multilingual display, fontsets: Non-latin display
multilingual display, third party programs on Windows 9x/ME: Third-party multibyte

news URLs, associating with Emacs: Using with Explorer
nmake, as default compile command: Default compile command
nmake, Incorrect DOS version messages: Incorrect DOS version

openssh: Tramp ssh
other ports of Emacs: Other versions of Emacs
other sources of information: More information
output not displaying, subprocesses: Subprocess buffering
overwriting the selected region: Highlight selection

paste with C-v: CUA
perl, avoiding buffering when used as a subprocess of Emacs: Perl script buffering
perl, debugging within Emacs: Perldb
perldb, using with Emacs: Perldb
pgp encryption, with GNU Privacy Guard: Encryption
plink: Tramp ssh
png, installing image support in Emacs: Image support
point and mark, highlighting the region between: Highlight selection
point to focus: Focus follows mouse
pop3, using Gnus: Incoming mail with Gnus
pop3, using rmail: Incoming mail with Rmail
precompiled binaries: Downloading
printing: Printing
PuTTY: Tramp ssh

quoting arguments to subprocesses: Quoting issues

rcs, version control integration with Emacs: Version control
recursive searching with grep: Recursive grep
region, highlighting: Highlight selection
registry, cleaning the Emacs settings: Uninstall
registry, setting the HOME directory in: Location of init file
remote hosts via ftp: Using FTP
remote hosts via ssh: Tramp ssh
remove Emacs: Uninstall
revision control, integration with Emacs: Version control
rmail, mail client: Incoming mail with Rmail
rsvg, installing image support in Emacs: Image support

scan all files, anti-virus option causing problems: Anti-virus
scan all files, anti-virus option causing problems: Shell commands do nothing
scan codes, modifying: Swap CapsLock and Control
scope of FAQ: Introduction
scrolling, with mouse wheel: Mouse wheel
searching through files with grep: Grep
selection, highlighting: Highlight selection
setbuf, using in subprocesses to prevent buffering: Subprocess buffering
setvbuf, using in subprocesses to prevent buffering: Subprocess buffering
shell commands not working: Shell commands do nothing
shell commands, suppressing echo: Shell echo
shell specific arguments: Shell echo
shell terminates when EOF sent to subprocess: Subprocess EOF
shell within emacs, using: Using shell
shell, Incorrect DOS version messages: Incorrect DOS version
shell, interacting badly with anti-virus: Anti-virus
shell, interacting badly with anti-virus: Shell commands do nothing
shell, using cygwin bash within Emacs: Bash
shift key, selecting with: CUA
shutdown, complaints about cmdproxy.exe running: Killing subprocesses
signatures on Emacs distribution, checking: Encryption
simulating three button mouse with two buttons: Mouse trouble
smtp server: Outgoing mail
sound, changing the beep: Beep sound
source control, integration with Emacs: Version control
source for Emacs: Downloading
spell checking: Spell check
SQL subprocess hanging: Subprocess buffering
ssh, accessing remote hosts within Emacs: Tramp ssh
ssh, password prompt not appearing when using with cvs: Subprocess buffering
standard Windows key bindings: CUA
Start Menu, creating icons for Emacs: Installing binaries
Start Menu, removing Emacs from: Uninstall
sub-processes, quoting arguments to: Quoting issues
subprocess starting causes floppy drive access: Subprocesses and floppy drive
subprocess, killing on Windows 95/98/ME: Killing subprocesses
subprocesses: Sub-processes
subprocesses, buffering output: Subprocess buffering
subprocesses, cygwin tools: Cygwin
subprocesses, gnuwin32: GnuWin32
subprocesses, hanging when reading input: Subprocess hang
subprocesses, interacting badly with anti-virus: Anti-virus
subprocesses, mingw and msys: MinGW
subprocesses, mingw-w64 and msys2: MinGW-w64
subprocesses, useful tools: Other useful ports
supported versions of Windows: Which versions of Windows
svn, version control integration with Emacs: Version control
swap right and middle mouse buttons: Mouse trouble
symlinks in dired, interpreting the same way as cygwin: Dired ls
synthesized italic and bold fonts: Bold and italic
system menu, simulating from lisp: Window operations

tar.gz files, how to unpack Emacs sources: Unpacking
telnet client, that works with Emacs: telnet
telnet, display size problems running emacs over: Console window size
telnet, in Emacs: telnet
tex: TeX
third mouse button, simulating: Mouse trouble
tiff, installing image support in Emacs: Image support
toolbar, installing color icons in: Image support
tramp, ftp: Using FTP
tramp, ssh: Tramp ssh
transient-mark-mode: Highlight selection
troubleshooting init problems: Troubleshooting init file
troubleshooting installation problems: Does not run
two button mouse: Mouse trouble
typesetting: TeX

UI, making Emacs more like other Windows apps: Make Emacs like a Windows app
uninstall Emacs: Uninstall
Unix line ends: Line ends
unpacking Emacs distribution: Unpacking
untarring Emacs distribution: Unpacking
unzipping Emacs distribution: Unpacking
upgrading Emacs: Uninstall
URLs, associating mail and news URLs with Emacs: Using with Explorer
useful tools: Other useful ports

vcvars32.bat: VC++ environment
version control, integration with Emacs: Version control
virus reported in Emacs: Virus
virus software, bad interaction with: Anti-virus
virus software, bad interaction with: Shell commands do nothing
VisEmacs, add in for MS Developer Studio: DevStudio
Visual Studio, keeping source in sync: Reverting buffers
Visual Studio, load in Emacs command: Edit MSVC
Visual Studio, using Emacs as editor in: DevStudio
vm, mail client: Incoming mail other

wanderlust, mail and news client: Incoming mail other
wheel mouse: Mouse wheel
where to get Emacs binaries: Downloading
where to get sources: Downloading
Why Windows: Why Emacs on Windows
wiki: More information
window not appearing, Emacs: Does not run
Windows 3.11 port: Other versions of Emacs
windows key, use as alt: Swap CapsLock and Control
Windows, making Emacs act more like: Make Emacs like a Windows app
Windows, versions: Which versions of Windows
WM_SYSCOMMAND, sending system commands from lisp: Window operations

X, making Windows behave like: Make Windows more like X
XLFD font names: Font names
xpm, installing image support in Emacs: Image support

zip files, how to unpack Emacs binaries: Unpacking

Jump to:   -   .   2   8   _  
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Z  



Latest versions of GDB might refuse to load the init file for security reasons, unless you customize GDB; alternatively, use an explicit source ./gdbinit command after entering GDB.