Frequently Asked Questions

It’s an homage to idsoftware’s classic game, whose source code was my first exposure to programming back in the Cretaceous period, when I was a wee lad (i.e. 1999).

That, and Emacs is an all-consuming black hole for those with yak shaving tendencies – and let’s be real, if you’re considering Emacs, that likely includes you. You’re doomed.

These four sections in our user manual are dedicated to answering this question:

• Why Emacs?
• Why not Emacs?
• Why Doom?
• Why not Doom?

No. I started Doom from scratch in 2014. I wrote it to learn Emacs and Emacs Lisp, and wasn’t aware of Spacemacs, Prelude, and others until much later.

That’s not to say Doom hasn’t taken any inspiration from them since. Early versions of Doom drew inspiration from Prelude’s project structure (until Doom introduced a module system) and some concepts (like SPC as a leader key) were adopted from Spacemacs or PRed from migrating users.

As our userbase grows, more similarities (and differences) will no doubt emerge.

…

Doom set out to have a package manager that fulfilled these five goals:

1. Scriptability: package management should be scriptable, so updating can be automated.
2. Reach: allow users to install packages from arbitrary sources (like github or gitlab), and from specific commits, branches or tags. Some plugins are out-of-date through official channels, have changed hands, have a superior fork, or aren’t available in ELPA repos.
3. Performance: lazy-loading the package management system is a tremendous boon to start up speed. Initializing package.el and straight (and/or checking that your packages are installed) or loading package autoloads files each time you start up is expensive.
4. Organization: as an Emacs config grows, in complexity and size, a clear separation of concerns becomes more important. Separating a package’s configuration from its installation makes for a better organized config.
5. Reproducibility: Emacs is a tumultuous ecosystem; packages break left and right, and we rely on hundreds of them. Pinning gives us a degree of reproducibility that significantly limits the damage unpredictable upstream changes can do – at least, until we’re ready to deal with them (or they’ve been dealt with upstream).

package.el offers none any of these, straight.el offers some of it, and Doom adds the rest.

It’s certainly not critical, but I believe a) faster software is always better UX, b) learned helplessness about Emacs’ startup performance will never fix the problem, and c) we shouldn’t have to manage yet-another-tool simply to get sane startup times out of Emacs.

A fast startup time facilitates:

• Emacs as a viable alternative to vim for quick, one-shot editing in the terminal (without -Q).
• Running multiple, independent instances of Emacs (e.g. on a per-project basis, or for nix-shell users, or to isolate one instance for IRC from an instance for writing code, etc).
• Quicker restarting of Emacs, to reload package settings or recover from disastrous errors which can leave Emacs in a broken state.
• Faster integration with “edit/open in Emacs” solutions (like atomic-chrome or org-protocol), and without a daemon.

It’s up to you to decide if these are good enough reasons not to use a daemon, but it’s nice to have more options, isn’t it?

In $HOME/.config/doom or $HOME/.doom.d (in that order).

Doom is XDG-compliant, and as of Emacs 27.1 so is Emacs. I.e. You can clone Doom to $HOME/.config/emacs instead of $HOME/.emacs.d.

For simplicity’s sake, our documentation always assumes you’re using $HOME/.emacs.d and $HOME/.doom.d.

Remember to run $ doom sync && doom build after moving $HOME/.emacs.d and/or $HOME/.doom.d.

This is explained in more detail on our Discourse.

The version is displayed in the dashboard buffer’s modeline.

Alternatively, use M-x doom/version or run $ doom version (on the command line) to see this information.

To update Doom run $ doom upgrade in the shell and restart Emacs.

If you’ve also up/downgraded Emacs, run $ doom build too.

There are many options. Emacs provides a number of keybind functions:

• define-key KEYMAP KEY DEF
• global-set-key KEY DEF
• local-set-key KEY DEF
• evil-define-key STATES KEYMAP KEY DEF &rest ...

However, Doom provides a more general map! macro, which conveniently wraps up the above four into a more succinct syntax. Comprehensive examples of map!’s usage can be found in its documentation (keyboard shortcut: <help> f map\!).

There are also live examples map!’s usage in config/default/+evil-bindings.el.

(This explanation comes from emacs-evil/evil’s readme)

An underscore “_” is a word character in Vim. This means that word-motions like w skip over underlines in a sequence of letters as if it was a letter itself. In contrast, in Evil the underscore is often a non-word character like operators, e.g. +.

The reason is that Evil uses Emacs’ definition of a word and this definition does not often include the underscore. Word characters in Emacs are determined by the syntax-class of the buffer. The syntax-class usually depends on the major-mode of this buffer. This has the advantage that the definition of a “word” may be adapted to the particular type of document being edited. Evil uses Emacs’ definition and does not simply use Vim’s definition in order to be consistent with other Emacs functions. For example, word characters are exactly those characters that are matched by the regular expression character class [:word:].

If you want the underscore to be recognized as word character, you can modify its entry in the syntax-table:

(modify-syntax-entry ?_ "w")

This gives the underscore the word syntax-class. You can use a mode-hook to modify the syntax-table in all buffers of some mode, e.g.

;; For python
(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w"))
;; For ruby
(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w"))
;; For Javascript
(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w"))

This is documented in detail in the user manual:

• How to change your leader keys
• How to bind new keys under the leader prefix
• How to bind aliases for your leader / localleader prefix

Doom uses the display-line-numbers package, which is built into Emacs 26+.

By disabling the :editor evil module.

Read the “Removing evil-mode” section in the module’s documentation for precise instructions.

• To change themes, add (setq doom-theme 'name-of-theme) to $DOOMDIR/config.el.
• To switch themes on-the-fly, type <help> t (M-x load-theme).
• To customize a theme, see our guide on the Discourse.

As a rule of thumb you should run $ doom sync whenever you:

• Update Doom with $ git pull instead of $ doom upgrade,
• Change your doom! block in $DOOMDIR/init.el,
• Change autoload files in any module (or $DOOMDIR),
• Or change the packages.el file in any module (or $DOOMDIR).
• Install an Emacs package or dependency outside of Emacs (i.e. through your OS package manager).

If anything is misbehaving, it’s a good idea to run $ doom sync first, which will regenerate your autoloads file (which tells Doom where to find lazy-loaded functions and libraries), install missing packages, and uninstall orphaned (unneeded) packages.

This command is never needed for changes to $DOOMDIR/config.el.

The -y and --yes flags (or the YES environment variable) will force doom to auto-accept confirmation prompts:

doom -y update
doom --yes update
YES=1 doom update

Short answer: it is safe to sync $DOOMDIR across systems, but not $EMACSDIR.

Long answer: $EMACSDIR/.local can contain baked-in absolute paths and non-portable byte-code. It is never a good idea to mirror it across multiple systems.

But if you absolutely must, remember to run $ doom sync && doom build on the target machine afterwards.

Delete $EMACSDIR/.local/straight and run $ doom sync.

…

s and S have been intentionally replaced with the evil-snipe plugin, which provides 2-character versions of the f/F/t/T motion keys, ala vim-seek or vim-sneak.

These keys were changed because they are redundant with cl and cc respectively (and the new behavior was deemed more useful).

If you still want to restore the old behavior, simply disable evil-snipe-mode:

;; in $DOOMDIR/config.el
(remove-hook 'doom-first-input-hook #'evil-snipe-mode)

Consult our troubleshooting guide. It will work you through some strategies to resolve the most common issues you’ll run into as an Emacs user.

There are many causes for slowness in Doom and/or Emacs. To document possible causes and workarounds, you’ll find a longer answer to this on our Discourse.

The most common cause for this is a ~/.emacs file. If it exists, Emacs will read this file instead of the ~/.emacs.d directory, ignoring Doom altogether.

If this isn’t the case, try running $ doom doctor. It can detect a variety of common issues and may give you some clues as to what is wrong.

This commonly means that Emacs can’t find your private doom config (in ~/.doom.d or ~/.config/doom). Make sure only one of these two folders exist, and that it has an init.el file with a doom! block. Running $ doom install will populate your private doom directory with the bare minimum you need to get going.

If nothing else works, run $ doom doctor. It can detect a variety of common issues and may give you some clues as to what is wrong.

The two most common causes for $PATH issues in Doom are:

1. Your shell configuration doesn’t configure $PATH correctly. If $ which <PROGRAM> doesn’t emit the path you expect on the command line then this is likely the case.
2. Your app launcher (rofi, albert, docky, dmenu, sxhkd, etc) is launching Emacs with the wrong shell, either because it defaults to a different shell from the one you use or the app launcher itself inherits the wrong environment because it was launched from the wrong shell.
3. You’re a Mac user launching Emacs from an Emacs.app bundle. MacOS launches these apps from an isolated environment.

As long as your shell is properly configured, there is a simple solution to issues #1 and #3: generate an envvar file by running $ doom env. This scrapes your shell environment into a file that is loaded when Doom Emacs starts up. Check out doom help env for details on how this works.

For issue #2, you’ll need to investigate your launcher. Our Discord is a good place to ask about it.

1. Make sure you don’t have both ~/.doom.d and ~/.config/doom directories. Doom will ignore the former if the latter exists.
2. Remember to run $ doom sync when it is necessary. To get to know when, exactly, you should run this command, run $ doom help sync.

If neither of these solve your issue, try $ doom doctor. It will detect a variety of common issues, and may give you some clues as to what is wrong.

Here are a few common causes for random crashes:

• On some systems (particularly MacOS), manipulating the fringes or window margins can cause Emacs to crash. This is most prominent in the Doom Dashboard (which tries to center its contents), in org-mode buffers (which uses org-indent-mode to create virtual indentation), or magit. There is currently no known fix for this, as it can’t be reliably reproduced. Your best bet is to reinstall/rebuild Emacs or disable the errant plugins/modules. e.g.

  To disable org-indent-mode:

  # ⎘

  ;; in $DOOMDIR/config.el
  (after! org
    (setq org-startup-indented nil))
  

  Or disable the :ui doom-dashboard & :tools magit modules (see #1170).

• Ligatures and some fonts can cause Emacs to crash. You may want to try a different font, or disable the :ui ligatures module.
• Some fonts seem to cause Emacs to crash when they lack support for a particular glyph (typically unicode characters). Try changing your font by changing doom-font or doom-unicode-font.

If these don’t help, check our troubleshooting guides for hard crashes or freezes/hangs.

You’ll find solutions on the emacswiki.

Doom highlights non-standard indentation. i.e. Indentation that doesn’t match the indent style you’ve set for that file. Spaces are Doom’s default style for most languages (excluding languages where tabs are the norm, like Go).

There are a couple ways to address this:

1. Fix your indentation! If it’s highlighted, you have tabs when you should have spaces (or spaces when you should be using tabs).

   Two easy commands for that:

   • M-x tabify
   • M-x untabify

2. Change indent-tabs-mode (nil = spaces, t = tabs) in $DOOMDIR/config.el:

   # ⎘

   ;; use tab indentation everywhere
   (setq-default indent-tabs-mode t)
   
   ;; or only in certain modes
   (setq-hook! 'sh-mode-hook indent-tabs-mode t) ; shell scripts
   (setq-hook! '(c-mode-hook c++-mode-hook) indent-tabs-mode t)  ; C/C++
   

3. Use editorconfig to configure code style on a per-project basis. If you enable Doom’s :tools editorconfig module, Doom will recognize .editorconfigrc files.
4. Or trust in dtrt-indent; a plugin Doom uses to analyze and detect indentation when you open a file (that isn’t in a project with an editorconfig file). This isn’t foolproof, and won’t work for files that have no content in them, but it can help in one-off scenarios.

If you’re getting this error you must reset the owner of C:\Users\USERNAME\.emacs.d to your own account:

1. Right-click the ~/.emacs.d/server directory in Windows Explorer,
2. Click Properties,
3. Select the “Security” tab,
4. Click the “Advanced” button,
5. Select the “Owner” tab,
6. Change the owner to your account name.

(source)

Emacs has a complex and hierarchical keybinding system. If a global keybind doesn’t take effect, it’s likely that another keymap is in effect with higher priority than the global keymap. For example, non-evil users may have tried something like this, to rebind C-left and C-right:

(map! "<C-left>"  #'something
      "<C-right>" #'something)

Just to find that the rebinding had no effect (i.e. C-h k C-left reports that it’s still bound to sp-backward-slurp-sexp). That’s because these keys are bound in smartparens-mode-map. They need to be unbound for your global keybinds to work:

(map! :after smartparens
      :map smartparens-mode-map
      [C-right] nil
      [C-left] nil)

I use [C-left] because it is easier to type than “<C-left>”, but are equivalent; two different ways to refer to the same key.

On our Github issue tracker, but please make sure:

• Your issue is not a support request, how-to question, or discussion. Those are better suited to our Discord or Discourse.
• Your issue hasn’t already been reported on Github or our Discourse.
• You can reproduce your issue on the latest version of Doom.
• You can reproduce your issue with your private configuration disabled (the sandbox can help).

Please discuss it with us on our Discord or Discourse. It will eventually end up in the #development category, where we keep track of feature requests. When we’re ready to assign it to a milestone, we’ll create a Github issue for it.

A list of community resources can be found in our documentation index, including links to our Discourse and Discord, where you can ask for help, talk shop, or just say hi.

Our Discord is an informal venue focused on being social and connecting directly with people (or Doom’s author, Henrik) and what they’re doing (e.g. streaming, talks, etc).

Our Discourse is a more formal venue for discussions and QnA’s. It’s also treated as our wiki; it is heavily curated for SEO, posterity, and clarity. Most questions will usually end up on Discourse in one form or another.

Which you join is up to you.

At this time, yes, but there are plans to create a Matrix server and bridge it to our Discord once their Spaces feature have matured.

Doom will never have an official IRC channel.

Our contributor’s manual covers many ways you can help. If code, documentation, and reports aren’t your thing, consider helping out the community as a participant or a moderator. Alternatively, you could sponsor Henrik so he can allocate more hours to Doom.

The project does not have a dedicated support team – only one overworked tomato and a handful of busy volunteers – so we must be strict about what issues we’ll process and there may be delays before your issue is reviewed and resolved. Sometimes the wait is unavoidable, but here’s what you can do to minimize this wait:

• Ensure there are no open, duplicate issues.
• Be descriptive and fill out the issue form as completely as possible; do not omit any of the fields.
• Give your issue a good title. e.g. Avoid something like “X stopped working”. Explain what “working” means to you instead.
• Focus on one thing per issue.
• Try to resolve the issue on your own (see our troubleshooting guide – it will also tell you how to collect more information for your report).
  • Make sure you can reproduce it on the latest commit of Doom Emacs – it may have already been resolved.
  • Make sure you can reproduce it on vanilla Doom – personal configuration could be the problem, in which case it is not a Doom issue.
  • Try to reproduce it in vanilla Emacs. If you can, this is likely an upstream issue and should be reported there instead.
  • See if $ doom sync -up && doom build fixes your issue.

If your issue still has the needs-triage label after 2 weeks, feel free to nudge @hlissner on Discord (in the #contributing channel).

The project does not have a dedicated support team – only one overworked tomato and a handful of busy volunteers – so there may delays before your PR is reviewed and merged. Sometimes this is unavoidable, but here’s what you can do to minimize this wait:

• Ensure there are no open PRs that tackle the same issue. If yours is intended to replace an existing one, please mention it.
• Include an explanation: why the PR is necessary, what it fixes, any gotchas I should be aware of, and issues it affects.
• Be acquainted with our Git commit conventions. Good commit ettiquette is required. Do not be afraid to rebase or force-push to tidy up your PR, once it is ready for review.
• Adhere to our code, documentation, and keybind conventions, where applicable.
• Ensure you’ve targeted the correct branch (develop, for now).
• Keep your PR focused. It shouldn’t do too much in too many places, if it can be avoided.

• If your PR introduces new tools, dependencies, or packages, I’m going to test them. It takes time to research them, acquire them, learn how to use them, and finally test them in the context of your PR. You can speed this up by including steps to set up an MVE with some test data.

  Extra points if you supply a shell.nix or Dockerfile to do so (if applicable).

@hlissner approves PRs in bulk and ahead of time (often days before merging them). This is done for a couple reasons:

• For a second chance to catch issues he may have missed.
• To have time cut out to handle issues that could arise from merging them.
• Because he has to go through a lot of issues/PRs each day.

If your PR was approved, you’ve nothing left to do but wait for Henrik to get off his glorious Canadian behind and merge it. If it’s been a week or so with no progress, feel free to nudge him on Discord (in the #contributing channel).

Due to the sheer complexity of Emacs, our issue tracker receives many false-positive, redundant, vague, or “support request”-type issues. This is a problem because they pollute our search results, make it difficult for maintainers (and users) to track real issues, and cost a lot of time to process; taking away time from real issues or project development.

Since Doom’s “support team” only consists of one overworked maintainer and a handful of busy volunteers, we have to be strict; we simply don’t have the capacity to chase issues that aren’t actionable, immediately reproducible, or can’t be investigated in a reasonable amount of time (which includes issues that are poorly researched or vague).

Posts that fall into these categories will be immediately closed, tagged for deletion, and given a brief explanation why, including instructions to overturn or contest the ruling if you believe it was a mistake.

Some examples:

• Performance issues without a clear or verifiable cause.
• Behavior that can’t be reproduced in vanilla Doom.
• An open request for “better X” without concrete goals.
• An issue that consists solely of “X doesn’t work” and little else.
• An issue that omits important information, like steps to reproduce and your system information.
• A post asking how to configure Emacs to achieve some effect (our issue tracker is for issues; ask these kinds of questions on Discord instead).
• An convoluted issue without a focus (e.g. presents multiple issues in one).

To ensure your issue makes the cut, please consult “How do I ensure my issue gets processed ASAP?” above.

See our contributing guide.

Yes! Maintainers, moderators, and regulars can get many of the same perks as sponsors.

• Maintainers look after one or more Doom modules. They keep me informed of needed updates and changes or make those changes themselves.
• Moderators look after our Github, Discord, and/or Discourse communities. They keep our issue tracker organized and keep the peace.
• Regulars are folks who are regularly active on our Discord and/or Discourse communities; they engage users, contribute to discussions, and answer questions.

Check out our contributing manual for ideas.

How I process issues (which I’ll use as a blanket term for bug reports, feature requests, questions, etc) on Github, Discourse, and Discord is: I triage, investigate, then resolve. Usually on separate days, depending on difficulty.

• If your issues get preferential treatment, they’ll be bumped to the top of the list of each step on their respective day.
• If your issues get first priority, I’ll do all three steps on your issue immediately and ASAP, before I move on other issues.