Frequently Asked Questions

Answers for common user questions and issues

1. Project

1.1. Why is it called Doom?

It’s an homage to idsoftware’s classic game, whose source code was my first exposure to programming, back in the Cretaceous period (1999).

Also, Emacs is an all consuming black hole. Its users doom themselves, eternally.

1.2. Is Doom a fork of Spacemacs/Prelude/etc?

No. I started it from scratch in mid-2014. I hadn’t heard of other distros until some years later, when a Doom user suggested this was a Spacemacs fork. I still see this misconception pop up from time to time.

However, that’s not to say Doom hasn’t taken any inspiration from these 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.

1.3. I am a beginner. Can I use Doom?

How new is “new”? Are you new to the shell? To programming in general? Or just Emacs/vim?

This isn’t a choice I can make for you, but if all of the above is true then Emacs is a rough place to start. With or without Doom.

Emacs’ main draw is its unparalleled extensibility, but anything so extensible has a steep learning curve. Expect a hefty commitment and a bumpy journey. Don’t pass up on the Documentation and seek help on our Discourse and Discord. Good luck!

1.4. Why such a complicated package management system?

Doom had five goals for its package manager:

  1. Scriptability: package management should be shell-scriptable, so updating can be automated.
  2. Reach: allow users to install packages from sources other than ELPA (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: an Emacs configuration grows so quickly, in complexity and size. A clear separation of concerns (configuration of packages from their installation) is easier to manage.
  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 (optional) config reproducibility and significantly limits the damage upstream changes can do – at least, until we’re ready to deal with them (or they’ve been dealt with upstream).

1.5. Why is startup time important? Why not use the daemon?

Obviously it’s 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 also 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 in Emacs” solutions (like atomic-chrome), 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?

1.6. Why should I use Doom instead of rolling my own config?

Two reasons:

  1. Doom’s package manager. It’s powered by straight.el, is declarative, non-rolling release and (nominally) reproducible; which is unique on the Emacs distro scene. Don’t let upstream issues surprise you. Roll back or re-pin packages when you don’t have the time to deal with issues.

    It also integrates with command line workflows, so automate to your heart’s content!

  2. Time. If you care about personalizing the software you use on a daily basis, even half as much as I do, then you need professional help, but you also know it is time consuming. Emacs out-of-the-box is a wasteland of archaic defaults, full of plugins rife with gotchas and oddities that may or may not be abandonware. It will be an uphill battle. Let Doom deal with all that noise. Save yourself some time.

    Time you could otherwise spend attending your daughter’s dance recitals, that baseball game your son’s team almost won last Thursday, or answering the court summons to fight for custody of your kids.

Also, Doom’s fast yo.

1.7. What version of Doom am I running?

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

Alternatively: M-x doom/version or bin/doom version (on the command line).

1.8. Does Doom respect XDG directory conventions

Yes. Your private config (normally in ~/.doom.d) can be moved to ~/.config/doom.

After Emacs 27 ~/.emacs.d can be moved to ~/.config/emacs.

2. How do I

2.1. Start over, in case something goes terribly wrong?

Delete ~/.emacs.d/.local/straight and run doom sync.

2.2. Bind my own keys (or change existing ones)?

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 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 (via SPC h f map\! or C-h f map\! – or in docs/api).

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

2.3. Include underscores in word motions?

(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"))

2.4. Change or alias the leader or localleader key?

These variables control what key to use for leader and localleader keys:

  • For Evil users:
    • doom-leader-key (default: SPC)
    • doom-localleader-key (default: SPC m)
  • For Emacs and Insert state (evil users), and non-evil users:
    • doom-leader-alt-key (default: M-SPC for evil users, C-c otherwise)
    • doom-localleader-alt-key (default: M-SPC m for evil users, C-c l otherwise)

e.g.

;;; add to $DOOMDIR/config.el
(setq doom-leader-key ","
      doom-localleader-key "\\")

2.5. Change the style of line-numbers (or disable them altogether)?

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

2.5.1. Disabling line numbers entirely

;;; add to $DOOMDIR/config.el
(setq display-line-numbers-type nil)
;; or
(remove-hook! '(prog-mode-hook text-mode-hook conf-mode-hook)
	      #'display-line-numbers-mode)

2.5.2. Switching to relative line numbers (permanently)

To change the style of line numbers, change the value of the display-line-numbers-type variable. It accepts the following values:

t            normal line numbers
'relative    relative line numbers
'visual      relative line numbers in screen space
nil          no line numbers

For example:

;;; add to $DOOMDIR/config.el
(setq display-line-numbers-type 'relative)

You’ll find more precise documentation on the variable through <help> v display-line-numbers-type (<help> is SPC h for evil users, C-h otherwise).

2.5.3. Switching the style of line numbers (temporarily)

Use M-x doom/toggle-line-numbers (bound to SPC t l by default) to cycle through the available line number styles in the current buffer.

e.g. normal -> relative -> visual -> disabled -> normal.

2.6. Customize, switch, or make new themes?

2.7. Remove Evil in favor of vanilla keybinds?

Yes! See the Removing evil-mode section in :editor evil’s documentation.

2.8. Know when to run $ doom sync?

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. doom sync is responsible for regenerating your autoloads file (which tells Doom where to find lazy-loaded functions and libraries), installing missing packages, and uninstall orphaned (unneeded) packages.

2.9. Suppress confirmation prompts while doom is running

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

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

2.10. Share/sync my config between multiple computers?

TL;DR: it is perfectly safe to sync ~/.doom.d, but not ~/.emacs.d.

Long answer: ~/.emacs.d/.local can contain baked-in absolute paths and non-portable byte-code. It is never a good idea to sync it across multiple computers.

If you must, for some reason, copy ~/.emacs.d from one system to another, remember to run doom sync && doom build on the target machine.

3. Performance

3.1. Why is Emacs/Doom slow?

See the answer on our Discourse.

3.2. How does Doom Emacs start up so quickly?

See the answer on our Discourse.

4. Community

4.1. I have an issue, where do I report it?

5. Internals

5.1. Where are packages cloned and built to?

Doom has configured straight to clone packages to ~/.emacs.d/.local/straight/repos/REPO-NAME and build them (generate autoloads, byte-compile, and symlink) to ~/.emacs.d/.local/straight/build/PACKAGE-NAME.

6. Contributing

6.1. How can I ensure my PR gets merged/reviews ASAP?

6.2. What should I know if I want to make a pull request to Doom?

  1. I like clean commit histories. Do not be afraid to rebase or force-push to tidy them up (unless you are working with a team on said PR, in that case save the rebasing for when it’s ready for review).

6.3. My PR was approved but not merged, what gives?

@hlissner approves PRs ahead of time so he can merge PRs in bulk later.

6.4. Why was my issue tagged “delete me”?

Due to the sheer complexity of Emacs, our issue tracker receives many false-positive, redundant, irrelevant, or “support request”-type issues. These pollute our search results and make it difficult for users (and maintainers) to find real issues, so they are deleted after a grace period.

To avoid this, please make sure you’ve thoroughly consulted the troubleshooting section in the manual before you post a bug report. It will help you identify the nature of your issue earlier.

How-to questions, discussion posts, and support requests do not belong on our issue tracker. Please post those on our Discourse instead.

6.5. How do I create and maintain a PR branch for Doom Emacs?

See our contributing guide.