In a situation where Emacs is not behaving like I want, what can I do to troubleshoot the problem? What steps can I take to find and fix the problem myself?

Or, failing that, how can I gather useful information that so that people here (or on the mailing list or other forums) can help me with my problem?

My Emacs includes many packages, a collection of snippets copy & pasted (or killed & yanked) from all over the internet, and my own custom elisp, some of which I don't recall writing, or no longer understand. Is there a way to make sense of all of these complications?

  • 1
    Not sure if this is the best place for this, but there are a lot of questions that get answers/comments requesting emacs -Q as a first step. I wrote this up as something to link those questions to as generic help for new users.
    – Tyler
    Nov 4, 2016 at 22:30
  • 1
    Yup, it is the best place for this. Actually, such a question was suggested (almost) 2 years ago: meta.emacs.stackexchange.com/q/198/184 Thanks!
    – T. Verron
    Nov 4, 2016 at 22:46

1 Answer 1


Step 1: running emacs -Q

The first thing you need to do is run emacs without any of your customizations. If you can reproduce the problem in vanilla Emacs, it may actually be a bug in Emacs itself. That's rare, but we rule it out as a first step.

If you start Emacs from the command line with the -Q flag, i.e., emacs -Q, you'll get a bare or 'vanilla' emacs, with none of your local customizations loaded. Does your problem still occur? If so, skip down to "Providing a Bug Recipe".

Note: emacs -q

While emacs -Q runs emacs without any customizations, emacs -q runs it without user customizations, but still runs site customizations. If you have a bug that occurs with emacs -q, but not emacs -Q, then the problem is in your site config. In that case, you need to find the file site-start.el. It's location depends on your OS. Some Linux distributions put it in /etc/emacs/. It may also be in /usr/local/share/emacs/site-lisp/. The locate command line program may be helpful in tracking it down.

Step 1b: what if the problem is with a package?

If your problem is specific to a particular package, then obviously you can't reproduce it without loading that package. But you want to load only the package concerned, not all of your configuration. To do that, run emacs -Q again, and prepare a short script such as the following:

(require 'package)
(setq package-load-list
      '((package1 t)))

Replace package1 with the name of the package you want to load. If you need to load multiple packages, modify the script accordingly:

(require 'package)
(setq package-load-list
      '((package1 t)
        (package2 t)
        (package3 t)))

To load this code, you can paste it into the *scratch* buffer, and call M-x eval-buffer. (or any buffer, as long as it doesn't have any other code in it!).

At this point, you've loaded the package(s), and just the package(s) you're testing. If you can reproduce the problem now, skip down to "Providing a Bug Recipe".

Step 2: Finding a Bug in your .emacs

You've now confirmed that the problem is coming from something in your configuration ("the call is coming from inside the house!"). Your configuration may be many thousands of lines long, and may load many different files. To find the problem, you'll do a binary search, commenting out half the code at a time to narrow things down.1

  1. Open your regular emacs, emacs, without the -Q option.
  2. Open your config file (usually ~/.emacs or .emacs.d/init.el, if you can't find it try C-h v user-init-file)
  3. Select the first half of the file: C-space to set the mark, scroll down half-way to extend the region
  4. Comment out the selected region: M-; and save the file
  5. Open a new emacs (your test emacs), leaving the first emacs running. test emacs will read the reduced version of your config.
  6. Try to reproduce the problem in test emacs
  7. If you can't reproduce it, close test emacs, and in your original emacs undo the comment with C-/, and comment out half of the remaining code. Open a new test emacs and try again.
  8. If you can reproduce the problem, comment out half of the remaining code and see if the problem persists.
  9. Repeat this process until you find the smallest bit of your configuration necessary to reproduce the problem.

If your problem is with a specific package, you'll have to leave the code that loads that package uncommented, of course.

If your config file loads other files, you may end up extending your search into those files as well.

At this point, you may have found that the problem is due to just a line or two of code. You may even be able to fix it yourself. If so, congratulations, you've learned something! Otherwise, move along to step three.

Step 3: Providing a Bug Recipe

At this point, you should be able to provide a detailed bug recipe to post here. It should include:

  • Your Emacs version (you can get this from Emacs with M-x emacs-version
  • Your operating system (Windows #, Mac, Linux distribution)
  • The version of the package your struggling with, if applicable
  • The specific steps necessary to demonstrate the problem, including what you expect to happen, and what actually happens.

For example, I might post a question like this:

I'm having a problem with super-mode. When I use M-x sm-compile-code, it makes a withdrawal from my PayPal account.

Steps to reproduce:

Load super-mode:

(require 'package)
(setq package-load-list
      '((super-mode t)))
  • open a new file with C-x C-f my-code
  • enter a line of code:
10 goto 10
  • call M-x sm-compile-code

I expect this to invoke the super-compiler and compile my program. Instead, I see a message in the minibuffer "$100 transfered from paypal to super-mode author"

GNU Emacs
Debian Linux
Super-mode version 3.1415

1The Bug Hunter package might help you with this, (semi-)automatically bisecting your init file.

  • 2
    Maybe you could mention The Bug Hunter.
    – Omar
    Nov 4, 2016 at 23:56
  • Great guide; I'd add (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t), since there's a big change that the package causing issues is on MELPA only.
    – Clément
    May 8, 2020 at 3:23
  • 1
    @clement you only need to add the archive to install a new package. The code here will load any packages that you've already installed, you don't need to add the archive to your debugging setup
    – Tyler
    Jun 29, 2021 at 12:55
  • Good point, thanks!
    – Clément
    Jun 30, 2021 at 1:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.