Ispell.el Frequently Asked Questions

Last Modified:

  1. General Notes and Information
  2. General Questions
  3. Problems and Solutions
  4. Bugs
  5. Dictionary Questions
  6. Features and suggestions

A brief history of ispell

Ispell has a long and convoluted history. Originally called SPELL, it was written by Ralph E. Gorin in 1971. That version was written in assembly language for the DEC PDP-10 to run under the WAITS operating system at the Stanford Artificial Intelligence Laboratory. Subsequent versions, also in PDP-10 assembly language, were developed for the BBN TENEX, MIT ITS, and DEC TOPS-10 and TOPS-20 operating systems. It was later revised by W. E. Matson (1974), and W. B. Ackerman (1978), changing its name to ISPELL in the process.

In 1983, Pace Willisson converted this version to the C language and modified it to work under UNIX. This version of ispell only supported plain text and UNIX ROFF formats. Since I (Ken Stevens) was and abysmal speller, and most of the documents I wrote which had to be correctly spelled were written in LaTeX, I added a Tex parser to this version of ispell.

In 1987, Walt Buehring revised and enhanced ispell, and posted it to the Usenet along with a dictionary. Geoff Kuenning picked up this version of the C code, fixed many bugs, and added further enhancements. In 1988 Geoff got ambitious and rewrote major portions of the code, resulting in the table-driven multi-lingual version.

The first emacs interface with ispell was developed by Leigh Klotz in TECO when he was at the MIT AI Lab in 1980. He defined most of the emacs key bindings that are still in use today. By 1987 GNU Emacs had been developed and disseminated by Richard Stallman, and Walt wrote the first version of "ispell.el", the emacs interface we see today.

I was incredibly happy not to hack TECO code anymore, and picked up Walt's ispell.el. Walt had apparently left TI, and I was never able to contact him. Over the years, I have completely rewritten and enhanced his original e-lisp and the result is the version that is now available.

In the early 1990's Richard Stallman desired a version of Ispell to be placed under the copyleft. This resulted in the short-lived ispell version 4.0 that was developed at the FSF and then abandoned in favor of this version of ispell. We decided to keep the current version numbering scheme, so the latest version of ispell is 3.1. The C code remains under a Berkeley-like copyright, and I released ispell.el e-lisp to the copyleft in 1994.

Many enhancements, bug fixes, and features have been provided and suggested by other people. The contributions from those in the open source community are greatly appreciated and encouraged.
Return to FAQ index.

How do I get ispell?

The latest version of ispell.el is maintained on this site. There will always be some variance between what is distributed with GNU Emacs and the ispell source code, since this code is always being improved. Although the code available from this site is under development, it has been tested and is stable enough to be freely distributed.

The version numbers on this code slowly evolve, but I try to update the time stamps as I release changes. If you pick up a version from this site, be sure to look at the date.

You can also click here to get more complete download information.
Return to FAQ index.

How do I contribute to ispell?

Contributions to ispell.el are very welcome! (As you can see, I don't even have enough time to do a good job with this FAQ! ;-)

Bug fixes, enhancements, ideas for improvement, etc. are best submitted to or Changes submitted to the FSF or an Emacs project may not get integrated, or will get integrated much later and at a larger inconvenience to all than if the changes are sent to one of the addresses here.
Return to FAQ index.

Starting ispell gives version errors and fails

Ispell.el checks the ispell program for compatibility before launching an interactive spelling session. If an incompatible version is detected, you will receive and error message and the spell session will fail.

Check the version numbers to make sure you have compatible ispell.el and ispell programs. The compatible ispell version is at the top of the ispell.el file. You can check the legal versions supported by ispell by looking at the header of the version of ispell that is currently loaded by executing M-x eval-expression (find-file (locate-library "ispell.el")) in Emacs. (Latest versions are 3.3 for ispell.el and 3.1.20 patch1 for ispell.)

The remedy is to make sure the latest version of ispell and ispell.el are loaded and found in your current search paths. You may need to override the current search path if you install the program personally by setting the variable load-path in your .emacs with a command such as (set-variable 'load-path (cons (concat (getenv "HOME") "/src/emacs/site-lisp") load-path))
Return to FAQ index.

Umlats break words in ispell.el

Problem: Certain words are incorrectly split in ispell when checked inside emacs. This will typically happen with ISO character sets such as German, Brazilian, etc. For example, the word `Universitšt' will be split into `Universit' and `t'.

The following are possible reasons for this:

  1. Ispell was compiled using NO8BIT.

    Check this by typing
    ispell -vv
    from a shell.
    Recompile ispell if NO8BIT is defined.

  2. You have an incompatible ispell dictionary and ispell.el dictionary definition.

    There are several different character set mapping that can be defined in the ispell dictionary. This allows one to switch between spell checking using escape characters of various forms such as LaTeX format, using 8-bit ISO characters, etc. These are selected using the extended character mode in ispell.

    The character mappings are defined in the affix file. The dictionary is then built from this affix file. Unfortunately the names and conventions of the character mappings are not standard as the creator of the affix file can name and create character sets as they want. You can see the character set being used in the current spelling session with the command
    M-x eval-expression

    This should match the extended character set in the affix file that you desire to use.

    The extended character set for each dictionary is currently defined as the 6th element in the ispell dictionary definition. In the following definition it is defined as "~latin1" - which would appear as the "latin" character set in the deutsch.aff file.

        "[']" t ("-C" "-d" "deutsch") "~latin1" iso-8859-1)

    Unfortunately at this time each character set needs a different dictionary. This will be improved shortly.

  3. Some problems exist due to a bug in the extended character mode mapping in ispell. This bug exists for release 3.1.20.

    Apply the latest patch to your ispell version 3.1.20 to fix this.

Return to FAQ index.

Problems running under cygwin

Problem: Ispell will run on the command line but not in emacs when running under cygwin. You may get an error message stating that ispell exited with code 128.

This most likely occurs win the cygwin dll file is not found on your Windoze search path. Cygwin1.dll is responsible for implementing all Unix system calls under Windoze operating systems. The DLL must be found in the search path of any application that uses it, or the app will fail. In the case of Ispell, it will quit with a 128 return code if the DLL is not found.

Make sure that the cygwin DLL, normally located at something like is found on you system's search path. You can determine if this is the case by starting up a new command prompt, and typing:
echo %path%

If you have administrative privileges you can add the cygwin directory to the search path for everyone on the system. You can do this on Win NT, 2000, and XP by using the Control Panel to modify the system PATH variable.

If you lack administrative privileges, you can't change the system PATH variable, but you can define a user PATH in the Control Panel's editor box:

     Variable Name:   [PATH]
     Variable Value:  [D:\CYGWIN\BIN]

Don't type the square brackets! They only represent the text boxes you type into. Don't type the name of the DLL itself, just the directory it is in. Also, if you already have a user PATH variable defined, don't mess it up. Here is how to append to an already-existing PATH:

     Variable Value:  [...;D:\CYGWIN\BIN]

All of this will be appended to your system's PATH at system startup, but only for yourself, not other people.

The case of the variable name and variable value don't matter under Windows.

Return to FAQ index.

How do I check the version numbers?

Newer versions of ispell have a function check-ispell-version which determines whether the current version of ispell on your system is compatible with the e-lisp code in Emacs. Later versions of this function return the ispell version numbers.

Use the following steps to determine your version number(s):

Return to FAQ index.

How do I install ispell.el?

Once you download a new version of ispell.el you need to get it installed. This requires two steps: replacing the old ispell.el file or placing the new one in your "search path" earlier than the old version, and compiling the file.

  1. Uncompressing the download.

    Unfortunately there are a number of ways the program will download from the web based on the browser and plugins you are using.

    • If the program appears in your browser as text, save the file out with the File | Save As command from in your browser. Be sure to name the file ispell.el
    • If the file is downloaded and remains compressed, you will need to uncompress the file with the command
      gunzip -v ispell.el.gz

  2. Placing the new ispell.el in the correct location.

    Emacs uses a "search path" mechanism for finding libraries. The system library directories get loaded by all users. The system directories are typically the last in the search path, which allows one to override the default directories by placing directories earlier in the search path.

    If you want everyone on the system to get the ispell.el upgrade, you either need to put the program in the original system directory or in a directory for "global customizations". The original library directory is called something like `.../lisp' or `.../lisp/ispell'. The global customization directory will usually be named `.../site-lisp'.

    I suggest looking at the current installation, by following the "overwrite" directions below, and if that directory is not writable by you or you deem it unsatisfactory, you should put ispell.el in a new location.

    1. Overwrite the old ispell version with the new.

      This is the best option, but is only possible if you have write permission to the old directory. Following are the steps to do this:

      1. Locate the directory of the ispell version that you are currently using. This is achieved with the command in Emacs:

        M-x locate-library

        This will tell you where ispell.el is being loaded.

      2. Copy the new ispell.el to this directory and overwrite the old version you will get the new version in your search path.

        You may not want to do this if the load-path is the original install directory, something like: `.../lisp/ispell.el'. In this case, you may want to see the directions for installing in a new directory below.

    2. Place ispell.el in a new directory.

      For widest use, put the program in a "site-lisp" directory. You can determine the search path of your installation with the following steps:

      1. Start a new emacs session with the command
        emacs -q
        This makes sure you only get *system* libraries.
      2. Switch to the *scratch buffer.
      3. Type the following on a new line:
        (mapcan (lambda (x) (and (string-match "site-lisp" x) (cons x nil))) load-path)
        and hit CTL-j
        This will list all of the site-lisp directories in your search path.

        Alternatively, you can list your entire search path by putting the following on a separate line in the *scratch* buffer:
        and hit CTL-j
        (you can also get the same effect by evaluating the expression (insert (format "%s" load-path)).)

      If this list has a "site-lisp" directory, you can usually put ispell.el there and it will be in the search path for everyone.

      If you do not want to make the ispell.el upgrade available for everyone, then place ispell.el in your personal site-lisp directory. If you already have one, then you can find it by following the above three steps, except don't do step 1; start emacs as you normally do.

      If you don't have a site-lisp directory, you can create one. To place this directory in your search path, edit your .emacs file, and include something like the following command:
      (set-variable 'load-path (cons (concat (getenv "HOME") "/emacs/site-lisp") load-path))
      where the "emacs/site-lisp" is a directory you created in your home directory in this case. (You can of course make the directory be anywhere you want.)

  3. Compile ispell.el

    The next step is to compile the program.

    1. Visit the new ispell.el in emacs buffer. (^X^F DIR/ispell.el)
    2. Execute this command to compile ispell.el:
      M-x byte-compile-file

    This will give you a list of warnings. Most of these are of the sort "undefined variable ..." This should be okay, because ispell.el contains *lots* of dynamic features that depend on variables being set to direct its behavior. If you don't have all the options, then some warnings will be given at compile time.

  4. Check installation

    Check to make sure you are getting the correct version by the following steps:

    1. Either start a new emacs session, or execute the following command in the current session:
      M-x load-library

    2. Check the version number:
      M-x eval-expression

    This should be the same version number that you downloaded and installed. If this is not the case then execute `M-: locate-library ispell.el' to see which file is actually being loaded.
Return to FAQ index.

Can Ispell check duplicate words?

No it can't do that that yet. :-(
Return to FAQ index.

How do I install a new dictionary?

First you must install ispell. :-) Then follow these easy steps:

  1. You will need a dictionary and associated affix definition. We have compiled a list of publicly available dictionaries you can choose from. (Please give us any dictionaries you have that are not on this list!)
  2. Build the hash table by running the program buildhash on the dictionary. The following example uses the dictionary:
  3. Install the dictionary. Copy the .hash file to the install location.
    The correct directory can be found with the command ispell -vv | grep LIBDIR
    If this showed the directory "/usr/local/lib" then you would type:

Return to FAQ index.

Help running under MS windoze.

Ispell has been ported to OS/2 and MS-DOS. You can download the DOS/WIN32 binaries of ispell-3.1.20. Please see the README for this version.

There are currently a few issues with running ispell in emacs with the windoze pipes and processes that I am fixing. Expect these to be done by the end of the year.

Atamir Dias has supplied the following notes to help you get ispell correctly configured with emacs:

  1. Unzip the above version of ispell-3.1.20 to C:\ISPELL
  2. Set the search path to find ispell. In autoexec.bat or the WinNT configuration screen set:
  3. Build the dictionaries you will be using. Using the English dictionary as an example: Repeat these steps for all your dictionaries.

Return to FAQ index.

Configuring (X)Emacs to use aspell.

Ispell.el can run with either aspell or ispell. Ispell has the best interface to emacs through ispell.el, and is the recommended choice. Unfortunately some stock OS installs only come with aspell.

If you prefer aspell over ispell, set the custom variable `ispell-prefer-aspell' in customize or in your .emacs (or .xemacs/init.el in the case of XEmacs).

Return to FAQ index.

Linux problems

Many distributions of Linux provide "ancient" versions of ispell and ispell.el. Most of the problems stem from mixing new and old versions of the ispell program and ispell e-lisp codes. Several interfaces between the program and emacs code have been improved and enhanced over the years, resulting in incompatibilities.

Follow this link for directions on determining the version of ispell you are running.

The current version of ispell.el will communicate correctly with program version 3.1.12 or greater. We recommend you pick up and install the latest version of ispell and ispell.el.
Return to FAQ index.

How do I report bugs?

Report any bugs by sending e-mail to Please include the version numbers of ispell.el and ispell program, plus any backtraces or other information that will help.

If you have a solution to the problem, please include that! Bug fixes typically get rapidly addressed and included in the latest available version.
Return to FAQ index.

The same dictionary seems to be shared between multiple languages!

See if the file  ~/.ispell_words  exists. If so, this is a hold-over from the days when ispell only supported English. If this file is found, it will be used as your personal dictionary regardless of the language being used (unless you explicitly redefine the personal dictionary file in the ispell variable  ispell-personal-dictionary).

Simply rename  ~/.ispell_words  to  ~/.ispell_DICTNAME.   DICTNAME will be your default dictionary, so for English it will be  ~/.ispell_english,   Deutsch it will be  ~/.ispell_deutsch8,  etc. After this, ispell will use language-specific personal dictionaries. This will allow you to spell-check multiple dictionaries with separate personal customizations.
Return to FAQ index.

I get error messages stating I have illegal characters

The latest versions of ispell check the integrity of your personal dictionaries. If you have changed the definition the character set with a new installation, or if you have inserted characters outside the character set into your personal dictionary you will get this error message. For example, I used '-' as a boundarychar in my dictionary. Removing this from the boundarychar set resulted in these errors with words such as re-route. You may also get this error if you are using multiple dictionaries but have only a single personal dictionary.

The best solution is to manually edit the personal dictionary and remove any words with illegal character embeddings.
Return to FAQ index.

My new dictionary definitions don't appear.

Modifying or adding dictionary entries to ispell.el can be tricky. You can change them in ispell.el, quit and reload emacs, yet the changes won't appear!

This is the notorious "autoload" bug.

We want emacs to start up quickly, and the menus need to be defined at load time. The solution is to load all the common functions and define the menus at load time. This is accomplished by creating a file "loaddefs.el" which contains all the definitions.

The problem is that this file is created at compile time, so any dynamic changes to the autoloaded definitions typically will not be recognized.

There are two solutions:

  1. The global fix:

    • Edit the file loaddefs.el in your load-path to incorporate the new values for ispell-dictionary-alist-1 and ispell-dictionary-alist-2 with the values in the latest version of ispell.el (or with your new or modified dictionary definition).

    • Restarting emacs should then load up the modified dictionary definition and create an updated menu.

  2. The local fix:

      I recommend this fix only for debugging new dictionaries. If you update to a new dictionary then you should use the above option. If you don't have access to change loaddefs.el you should have a system administrator do this so everyone can enjoy the new dictionary!

    • Define the dictionaries:

      (setq ispell-dictionary-alist-1 your-new-dictionary-definition)
      (setq ispell-dictionary-alist-2 your-new-dictionary-definition)
      (setq ispell-dictionary-alist (append ispell-dictionary-alist-1
      (setq ispell-menu-map nil)
      (load-library "ispell")

    • This will reset your dictionary definitions, and can be put in your .emacs file.

    • If you wish to run this interactively, you can do so with the M-: command or M-x setq ... commands.

    • For XEmacs, set the variable ispell-menu-xemacs to nil rather than the variable ispell-menu-map.
Return to FAQ index.

How do I force a file to use a dictionary?

There is a "buffer-local" feature in ispell that allows you to define various features that are local to the particular buffer. One you should already know about is the ability to store misspellings that you want to accept for this buffer but not place in your general dictionary. (For you that don't know about this, you would use the `A' key. :-)

A "buffer-local" feature exists to define the dictionary. There are two methods that can be used, however, we strongly recommend the first method be used since the second may go away in the future.

  1. Use emacs local variables.

    Set the variable `ispell-local-dictionary' to the desired dictionary (a string) in emacs' local variables section. For example:

    ;;; Local Variables:
    ;;; ispell-local-dictionary: "castellano"
    ;;; End:

  2. Use ispell.el's custom keyword `Local IspellDict'.

    Include the following in the bottom of your document:

    ;;; Local IspellDict: "american"

A few notes:

You can find all the valid dictionary names by typing the following
M-x ispell-change-dictionary
and entering a `?'.

There is currently no automatic way to add the buffer-local dictionary definition like you can with local words.
Return to FAQ index.

Latex backslash bug - ispell 3.1.20

This bug has been fixed in ispell version 3.2

Version 3.1.20 contains an irritating bug when using latex that causes all sorts of problems when the backslash is used. (The backslash is a common character in latex that is used, among other things, to create a forced space similar to the tilde character.) In the current version, 3.1.20, the next TWO characters are skipped after a backslash. This can results in misspellings and the file being incorrectly parsed. (For example, if the text contains the sequence `\ $' math mode will not be entered until the matching $ which should end it, resulting in the body of the text not being spell checked and the math region being checked.)

This can be fixed by downloading the patch, installing the patch, and recompiling and installing ispell.

Follow these steps:

  1. downloading this patch and save it to your ispell 3.1.20 source directory as ispell-patch1.gz
  2. uncompress the file with gunzip -v ispell-patch1.gz
  3. Install the patch with the command
    patch < ispell-patch1
  4. Then recompile and install ispell as directed in the source documentation.
    Make sure to undefine NO8BIT and use a larger number for MASKBITS if you are using iso character sets.
Return to FAQ index.

Known bugs in ispell.el

These are some of the outstanding bugs in ispell. If you notice other bugs, please report them to

  1. Emacs version 20.3 and above will require ispell.el version 3.1 or greater. Otherwise there will be errors when multibyte and extended characters are used.
  2. There are some problems with some MULE multibyte characters that don't get mapped into the dictionary used by ispell. This will cause an `alignment error' to occur.
Return to FAQ index.

I get lots of messages when compiling ispell.el

When compiling ispell.el you will get a number of warnings like the following:

** reference to free variable start
** reference to free variable end
** assignment to free variable start
** assignment to free variable end
** reference to free variable mh-ins-buf-prefix
** The following functions are not known to be defined: framepop-display-buffer

These messages are normal and can be ignored.

There are two reasons for these messages:

  1. The emacs lisp parser reports warnings for variables that are lexically parsed. The variables `start' and `end' are set in their lexical context which produces this error message.
  2. Ispell supports numerous optional features. These features have configuration information or functions that are only defined if the feature is used. If you do not use a particular feature (such as `framepop' in the above example) you will get a warning message that variables or functions for that feature are not defined.
Return to FAQ index.

Skipping spelling in AMS tex math modes.

All latex environments are not supported in ispell. However, with the general region-skipping ability they can be added.

If you use the AMS tex gather environment a lot, you may want to define it as a region to skip. The following shows you how to do this in ispell.el.

Modify the definition of ispell-tex-skip-alists in ispell.el (or set the variable in your .emacs file). The definition for gather must be added in the delimited section. In the example below it was placed after the verbatim definition:

(defvar ispell-tex-skip-alists
  '((("%\\[" . "%\\]")
     ;; All the standard LaTeX keywords from L. Lamport's guide:
     ;; \cite, \hspace, \hspace*, \hyphenation, \include, \includeonly, \input,
     ;; \label, \nocite, \rule (in ispell - rest included here)
     ("\\\\addcontentsline"              ispell-tex-arg-end 2)
     ("\\\\add\\(tocontents\\|vspace\\)" ispell-tex-arg-end)
     ("\\\\\\([aA]lph\\|arabic\\)"	 ispell-tex-arg-end)
     ("\\\\author"			 ispell-tex-arg-end)
     ("\\\\bibliographystyle"		 ispell-tex-arg-end)
     ("\\\\makebox"			 ispell-tex-arg-end 0)
     ;;("\\\\epsfig"		ispell-tex-arg-end)
     ("\\\\document\\(class\\|style\\)" .
      "\\\\begin[ \t\n]*{[ \t\n]*document[ \t\n]*}"))
    (;; delimited with \begin.  In ispell: displaymath, eqnarray, eqnarray*,
     ;; equation, minipage, picture, tabular, tabular* (ispell)
     ("\\(figure\\|table\\)\\*?"  ispell-tex-arg-end 0)
     ("list"			  ispell-tex-arg-end 2)
     ("program"		. "\\\\end[ \t\n]*{[ \t\n]*program[ \t\n]*}")
     ("verbatim\\*?"	. "\\\\end[ \t\n]*{[ \t\n]*verbatim\\*?[ \t\n]*}")
     ("gather\\*?"	. "\\\\end[ \t\n]*{[ \t\n]*gather\\*?[ \t\n]*}")))
  "*Lists of regions to be skipped in TeX mode.
First list is used raw.
Second list has key placed inside \\begin{}.

Delete or add any regions you want to be automatically selected
for skipping in latex mode.")

You can also do this for other latex commands such as align, \psfragc, \epsfig, etc.
Return to FAQ index.

Comments are welcome. Please send e-mail to

Copyright © 1998 - 2003 - All rights reserved
Last Modified: